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Introduction 



If you are developing 

a 16-bit DOS-only 

application, you can 

also use the routines 

described in the DOS 

Reference 



This manual contains definitions of the Borland C++ classes, nonprivate 
class members, library routines, common variables, and common defined 
types for windows programming. 

If you're new to C or C++ programming, or if you're looking for informa- 
tion on the contents of the Borland C++ manuals, see the introduction in 
the User's Guide. 

Here is a summary of the chapters in this manual: 

Chapter 1 : Library cross-reference provides an overview of the Borland 
C++ library routines and header files. After describing the static and 
dynamic-link libraries, this chapter lists the header files, and then groups 
the library routines according to the tasks they commonly perform. 

Chapter 2: The main function discusses arguments to main (including wild- 
card arguments), provides some example programs, and describes Pascal 
calling conventions and the value that main returns. 

Chapter 3: Run-time functions is an alphabetical reference of Borland C++ 
library functions. Each entry gives syntax, portability information, an 
operative description, and return values for the function, together with a 
reference list of related functions. 

Chapter 4: Global variables defines and discusses Borland C++'s global 
variables. You can use these to save yourself a great deal of programming 
time on commonly needed variables (such as dates, time, error messages, 
stack size, and so on). 

Chapter 5: The C++ iostream classes describes the classes that provide 
support for input and output in C++ programs. 

Chapter 6: Persistent stream classes and macros describes the persistent 
streams classes and macros. 

Chapter 7: The C++ container classes describes the container classes 
provided by Borland C++ such as array, stack, and linked list. 

Chapter 8: The C++ mathematical classes describes how to use bed and 

complex classes. 

Chapter 9: Class diagnostic macros describes the classes and macros that 
support object diagnostics. 
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Chapter 10: Run-time support describes functions and classes that let you 
control the way your program executes at run time in case the program 
runs out of memory or encounters some exception. 

Chapter 1 1 : C++ utility classes describes the C++ date, string, and time 
classes. 
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Library cross-reference 



If you are developing 

a 16-bit DOS-only 

application, you can 

also use the routines 

described in the DOS 

Reference 



This chapter provides an overview of the Borland C++ library routines and 
header files. Library routines are composed of classes, functions, and 
macros that you can call from within your C and C++ programs to perform 
a wide variety of tasks. These tasks include low- and high-level I/O, string 
and file manipulation, memory allocation, process control, data conversion, 
mathematical calculations, and much more. 

This chapter provides the following information: 

■ Names the static and dynamic-link libraries, files, and subdirectories 
found in the LIB and BIN subdirectories, and describes their uses. 

■ Explains why you might want to obtain the source code for the Borland 
C++ run-time library. 

■ Lists and describes the header files. 

■ Categorizes the library routines according to the type of tasks they 
perform. 



Reasons to access the run-time library source code 

There are several good reasons you might want to obtain the source code 
for the run-time library routines: 

■ A particular function you want to write might be similar to, but not the 
same as, a Borland C++ function. With access to the run-time library 
source code, you can tailor the library function to suit your needs, and 
avoid having to write a separate function of your own. 

■ Sometimes, when you're debugging code, you might want to know more 
about the internals of a library function. 

■ If you want to delete the leading underscores on C symbols, access to the 
run-time library source code will let you do so. 

■ You can learn a lot from studying tight, professionally written library 
source code. 
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For all these reasons, and more, you will want to have access to the Borland 
C++ run-time library source code. Because Borland believes strongly in the 
concept of "open architecture/' we have made the Borland C++ run-time 
library source code available for licensing. All you have to do is fill out the 
order form distributed with your Borland C++ package, include your pay- 
ment, and we'll ship you the Borland C++ run-time library source code. 



The run-time libraries 



The run-time libraries are divided into static (OBJ and LIB) and dynamic- 
link (DLL) versions. These different versions of the libraries are installed in 
separate directories. The static and dynamic libraries are described in 
separate tables. 



See the 

ObjectWindows 

Reference Guide for 

information about the 

libraries and DLLs 

specific to 

ObjectWindows. 



The static 
libraries 



Several versions of the run-time library are available. For example, there 
are memory-model-specific versions, diagnostic versions, and 16- and 32- 
bit-specific versions. There are also optional libraries that provide 
mathematics, container, ObjectWindows development, and international 
applications. 

Here are some guidelines for selecting which run-time libraries to use: 

h Segmented memory-model libraries are supported only in 16-bit 
programs. Tiny and huge memory models are not supported. 

a 16-bit DLLs are supported only in the large memory model. 

d For 32-bit programs, only the flat memory model is supported. 

■ 32-bit console and GUI programs require different startup code. 

□ Multithread applications are supported only in 32-bit programs. 

The static (OBJ and LIB) version of the Borland C++ run-time library is con- 
tained in the LIB subdirectory of your installation. For each of the library 
file names, the '?' character represents one of the four (compact, small, 
medium, and large) distinct memory models supported by Borland. Each 
model has its own library file and math file, containing versions of the 
routines written for that particular model. 

The following table identifies the default run-time libraries used with each 
compiler. See the User's Guide for discussions about compiling and linking. 
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Table 1.1: Default run-time libraries 



Compiler 



Application 



Default libraries 



BCC.EXE 


16-bit Windows 


COWS.OBJ, CWS.LIB, MATHWS.LIB, IMPORT.UB 


BCC32.EXE 


Win32 


C0X32.OBJ, CW32.LIB, IMPORT32.LIB 


BCW.EXE 


Same as BCC.EXE 


SameasBCC.EXE 


BCWS32.EXE 


Same as BCC32.EXE 


Same as BCC32.EXE 



The following table lists the names and uses of the Borland C++ static 
libraries; it also lists the operating system under which each library item is 
available. See the User's Guide for information on linkers, linker options, 
requirements, and selection of libraries. 



Table 1 .2: Summary of static run-time libraries 



File name 


Application 


Use 


Directory of BC4\UB 




BIDSDI.LIB 


Win 16 


16-bit diagnostic, dynamic BIDS import library for BIDS40D.DLL 


BIDSI.UB 


Win 16 


16-bit dynamic BIDS import library for BIDS40.DLL 


BIDSF.UB 


Win32s, Win32 


32-bit BIDS library 


BIDSDF.UB 


Win32s, Win32 


32-bit diagnostic BIDS library 


BIDSFI.LIB 


Win32s, Win32 


32-bit dynamic BIDS import library for BIDS40F.DLL 


BIDSDFI.LIB 


Win32s, Win32 


32-bit diagnostic, dynamic BIDS import library for BIDS40DF.DLL 


BIDSDB7.UB 


Win 16 


16-bit diagnostic BIDS library 


BIDSZLIB 


Win 16 


16-bit BIDS library 


BWCC.LIB 


Win 16 


16-bit import library for BWCC.DLL 


BWCC32.LIB 


Win32s, Win32 


32-bit import library for BWCC32.DLL 


C0D32.OBJ 


Win32s, Win32 


32-bit DLL startup module 


CODZOBJ 


Win 16 


1 6-bit DLL startup module 


C0W32.OBJ 


Win32s, Win32 


32-bit GUI EXE startup module 


COWZOBJ 


Win 16 


1 6-bit EXE startup module 


C0X32.OBJ 


Win32 


32-bit console-mode EXE startup module 


CRTDLL.LIB 


Win 16 


16-bit dynamic import library for BC40RTLDLL 


CW32.LIB 


Win32s, Win32 


32-bit GUI single-thread library 


CWZLIB 


Win 16 


16-bit library 


CW32I.LIB 


Win32s, Win32 


32-bit single-thread, GUI, dynamic RTL import library for CW32.DLL 


CW32MT1IB 


Win32 


32-bit GUI multithread library 
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Table 1 .2: Summary of static run-time libraries (continued) 



CW32MTI.LIB 


Win32 


IMPORT.LIB 


Win 16 


IMPORT32.LIB 


Win32s, Win32 


MATHW7.LIB 


Win 16 


W32SUT16.LIB 


Win 16 


W32SUT32.LIB 


Win32s 


OBSOLETE.LIB 


Win 16, Win32, Win32s 



32-bit multithread, GUI, dynamic RTL import libraryforCW32MT.DLL 

16-bit import library for Windows 3.1 

32-bit import library; use with IMPRTW32.UB 

16-bit math libraries 

16-bit universal thunking library 

32-bit universal thunking library 

Provides obsolete global variables. 



Directory of BC4\LIB\16-BIT 

FILES.C Win 16 

FILES2.C Win 16 

MATHERR.C Win 16 

MATHERRLC Win 16 



Increases the number of file handles 

Increases the number of file handles 

Sample of a user-defined floating-point math exception handler for float and 
double types 

Sample of a user-defined floating-point math exception handler for long double 
type 



Directory of BC4\LIB\32-BIT 

FILES.C Win32s, Win32 

FILES2.C Win32s, Win32 

FILEINFO.OBJ Win32s, Win32 

GP.OBJ Win32s, Win32 

MATHERR.C Win32s, Win32 

MATHERRL.C Win32s, Win32 

WILDARGS.OBJ Win32 



Increases the number of file handles 

Increases the number of file handles 

Passes open file-handle information to child processes 

Prints register-dump information when an exception occurs 

Sample of a user-defined floating-point math exception handler for float and 
double types 

Sample of a user-defined floating-point math exception handler for long double 
type 

Transforms wild-card arguments into an array of arguments to main in console- 
mode applications 



Directory of BC4\UB\STARTUP 

BUILD-CO.BAT Win 16 
C0D.ASM Win 16 

COWASM Win 16 

RULES.ASI Win 16 



Batch file to build C0D7.OBJ, C0F7.OBJ, and COWZOBJ 

Source for COD ?.OBJ 

Source for C0W7.OBJ 

Assembly rules for COD.ASM and COWASM 



The dynamic-link 
libraries 



The dynamic-link (DLL) version of the run-time library is contained in the 
BIN subdirectory of the installation. Several versions of the DLL libraries 
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are available. For example, there are diagnostic versions, 16- and 32- 
bit-specific versions, and versions that support multithread applications. 

In the 16-bit specific version, only the large-memory model DLL is pro- 
vided. No other memory-model is supported in a 16-bit DLL. 

The following table lists the Borland C++ DLL names and uses, and the 
operating system under which the library item is available. See the User's 
Guide for information on linkers, linker options, requirements, and selection 
of libraries. 



Table 1 .3: Summary of dynamic link libraries 



File name 



Application 



Use 



Directory of BC4\BIN 

BC40RTL.DLL Win 16 

BIDS40.DLL 

BIDS40D.DLL 

BIDS40F.DLL 

BIDS40DF.DLL 

CW32.DLL 

CW32MT.DLL 

LOCALE.BLL 



Win 16 

Win 16 

Win32s, Win32 

Win32s, Win32 

Win32s, Win32 

Win32 

Win 16, Win32s, Win32 



16-bit, large-memory model 

16-bit, BIDS 

16-bit, diagnostic BIDS 

32-bit BIDS 

32-bit diagnostic BIDS 

32-bit, single thread 

32-bit, multithread 

Locale library 



The Borland C++ header files 



C++ header files, and 

header files defined 

by ANSI C, are 

marked in the margin. 



Header files provide function prototype declarations for library functions. 
Data types and symbolic constants used with the library functions are also 
defined in them, along with global variables defined by Borland C++ and 
by the library functions. The Borland C++ library follows the ANSI C 
standard on header-file names and their contents. 



Header file 



Description 



alloc.h Declares memory-management functions (allocation, deallocation, and so on). 

assert.h 1 Defines the assert debugging macro. 

bcd.h 2 Declares the C++ class bed and the overloaded operators for bed and bed math functions. 

bios.h Declares various functions used in calling IBM-PC ROM BIOS routines. 

checks.h 2 Defines PRECONDITION, WARN, and TRACE diagnostic macros. 
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complex.h 2 Declares the C++ complex math class. 

conio.h Declares various functions used in calling the operating-system console I/O routines. The functions 
defined in this header file cannot be used in GUI applications. 

constrea.h 2 Declares C++ classes and methods to support console output. 

cstring.h 2 Declares the ANSI C++ string class support. 

ctype.h 1 Contains information used by the character classification and character conversion macros (such as 
isalpha and toascii). 

dir.h Contains structures, macros, and functions for working with directories and path names. 

direct.h Defines structures, macros, and functions for dealing with directories and path names. 

dirent.h Declares functions and structures for POSIX directory operations. 

dos.h Defines various constants and gives declarations needed for DOS and 80x86-specific calls. 

errno.h 1 Defines constant mnemonics for the error codes. 

except.h 2 Declares ANSI C++ exceptions support. 

excpt.h Declares C exceptions support. 

fcntl.h Defines symbolic constants used in connection with the library routine open. 

float.h 1 Contains parameters for floating-point routines. 

fstream.h 2 Declares the C++ stream classes that support file input and output. 

generic.h Contains macros for generic class declarations. 

io.h Contains structures and declarations for low-level inputbutput routines. 

iomanip.h 2 Declares the C++ streams I/O manipulators and contains templates for creating parameterized 
manipulators. 

iostream.h 2 Declares the basic C++ streams (I/O) routines. 

limits.h 1 Contains environmental parameters, information about compile-time limitations, and ranges of integral 
quantities. 

locale.h 1 Declares functions that provide country- and language-specific information. 

sys\locking.h Definitions for mode parameter of locking function. 

malloc.h Memory-management functions and variables. 

math.h 1 Declares prototypes for the math functions and math error handlers. 

mem.h Declares the memory-manipulation functions. (Many of these are also defined in string.h.) 

memory.h Memory-manipulation functions. 

new.h 2 Access to_neiv_/7a/?cf/erand set_new_handler. 

process.h Contains structures and declarations for the spawn... and exec... functions. 

ref.h 2 Provides support for reference counting. Used with the string class. 

regexp.h 2 Implements regular-expression searching. 
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search.h 
setjmp.h 1 

share.h 

signal.h 1 

stdarg.h 1 

stddef.h 1 
stdio.h 1 

stdiostr.h 2 

stdlib.h 1 

string.h 1 
strstrea.h 2 
sys\stat.h 
time.h 1 

sys\timeb.h 

sys\types.h 

typeinfo.h 2 

utime.h 

values.h 

varargs.h 

1 Defined by ANSI C. 

2 C++ header files. 



Declares functions for searching and sorting. 

Defines a type jmp_buf used by the longjmp and setjmp functions and declares the functions longjmp and 
setjmp. 

Defines parameters used in functions that make use of file-sharing. 

Defines constants and declarations for use by the signal and raise functions. 

Defines macros used for reading the argument list in functions declared to accept a variable number of ar- 
guments (such as vprintf, vscanf, and so on). 

Defines several common data types and macros. 

Defines types and macros needed for the standard I/O package defined in Kemighan and Ritchie and 
extended under UNIX System V. Defines the standard I/O predefined streams stdin, stdout, stdpm, and 
stderr, and declares stream-level I/O routines. 

Declares the C++ (version 2.0) stream classes for use with stdio FILE structures. You should use 
iostream.h for new code. 

Declares several commonly used routines: conversion routines, search/sort routines, and other 
miscellany. 

Declares several string-manipulation and memory-manipulation routines. 

Declares the C++ stream classes for use with byte arrays in memory. 

Defines symbolic constants used for opening and creating files. 

Defines a structure filled in by the time-conversion routines asctime, localtime, and gmtime, and a type 
used by the routines dime, difftime, gmtime, localtime, and stime; also provides prototypes for these 
routines. 

Declares the function ftime and the structure timeb that ftime returns. 

Declares the type timej used with time functions. 

Provides declarations for ANSI C++ run-time type identification (RTTI). 

Declares the utime function and the utimbuf struct that it returns. 

Defines important constants, including machine dependencies; provided for UNIX System V compatibility. 

Definitions for accessing parameters in functions that accept a variable number of arguments. Provided for 
UNIX compatibility; you should use stdarg.h for new code. 



Library routines by category 



The Borland C++ library routines perform a variety of tasks. The routines, 
along with the header files in which they are declared, are listed by 
category of task performed. 
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C++ prototyped 
routines 



Certain routines described in this book have multiple declarations. You 
must choose the prototype appropriate for your program. In general, the 
multiple prototypes are required to support the original C implementation 
and the stricter and sometimes different C++ function declaration syntax. 
For example, some string-handling routines have multiple prototypes 
because in addition to the ANSI-C specified prototype, Borland C++ 
provides prototypes consistent with the ANSI C++ draft. 



getvect 

max 

memchr 

min 

setvect 



(dos.h) 

(stdlib.li) 

(string.h) 

(stdlib.h) 

(dos.h) 



strchr 
strpbrk 
strrchr 
strstr 



(string.h) 
(string.h) 
(string.h) 
(string.h) 



Classification 
routines 



These routines classify ASCII characters as letters, control characters, 
punctuation, uppercase, and so on. 



isalnum 

isalpha 

isascii 

iscntrl 

isdigit 

isgraph 



(ctype.h) 
(ctype.h) 
(ctype.h) 
(ctype.h) 
(ctype.h) 
(ctype.h) 



islower 

isprint 

ispunct 

isspace 

isupper 

isxdigit 



(ctype.h) 
(ctype.h) 
(ctype.h) 
(ctype.h) 
(ctype.h) 
(ctype.h) 



Console I/O 
routines 



These routines output text to the screen or read from the keyboard. They 
cannot be used in a GUI application. 



cgets 

clreol 

clrscr 

cprintf 

cputs 

delline 

getpass 

gettext 

gettextinfo 

gotoxy 

highvideo 

insline 

lowvideo 



(conio.h) 
(conio.h) 
(conio.h) 
(conio.h) 
(conio.h) 
(conich) 
(conio.h) 
(conio.h) 
(conio.h) 
(conio.h) 
(conio.h) 
(conio.h) 
(conich) 



movetext 


(conio.h) 


normvideo 


(conio.h) 


putch 


(conio.h) 


put text 


(conio.h) 


_setcursortype 


(conio.h) 


textattr 


(conio.h) 


textbackground 


(conio.h) 


textcolor 


(conio.h) 


textmode 


(conio.h) 


ungetc 


(stdio.h) 


wherex 


(conio.h) 


wherey 


(conio.h) 


window 


(conio.h) 



Conversion 
routines 



These routines convert characters and strings from alpha to different 
numeric representations (floating-point, integers, longs) and vice versa, and 
from uppercase to lowercase and vice versa. 
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at of 
atoi 
atol 
ecvt 
fcvt 
govt 
itoa 
Itoa 
strtod 



(stdlib.h) 
(stdlib.h) 
(stdlib.h) 
(stdlib.h) 
(stdlib.h) 
(stdlib.h) 
(stdlib.h) 
(stdlib.h) 
(stdlib.h) 



strtol 

_strtold 

strtoul 

toascii 

Jolower 

tolower 

Joupper 

toupper 

ultoa 



(stdlib.h) 
(stdlib.h) 
(stdlib.h) 
(ctype.h) 
(ctype.h) 
(ctype.h) 
(ctype.h) 
(ctype.h) 
(stdlib.h) 



Diagnostic 


These routines 


provide built-in 


. troubleshooting capability. 




routines 












assert 


(assert.h) 


perror 


(errno.h) 




CHECK 


(checks.h) 


PRECONDITION 


(checks.h) 




jnatherr 


(math.h) 


TRACE 


(checks.h) 




jnatherrl 
These routines 


(math.h) WARN 
manipulate directories and path names. 


(checks.h) 


Directory control 




routines 












chdir 


(dir.h) 


_getdcwd 


(direct.h) 




_chdrive 


(direct.h) 


getdisk 


. (dir.h) 




closedir 


(dirent.h) 


jnakepath 


(stdlib.h) 




_dos_findfirst 


(dos.h) 


mkdir 


(dir.h) 




_dos_findnext 


(dos.h) 


mktemp 


(dir.h) 




_dos_getdiskfree 


(dos.h) 


opendir 


(dirent.h) 




_dos_getdrive 


(dos.h) 


readdir 


(dirent.h) 




_dos_setdrive 


(dos.h) 


rewinddir 


(dirent.h) 




findfirst 


(dir.h) 


rmdir 


(dir.h) 




findnext 


(dir.h) 


_searchenv 


(stdlib.h) 




fnmerge 


(dir.h) 


searchpath 


(dir.h) 




fnsplit 


(dir.h) 


_searchstr 


(stdlib.h) 




Jullpath 


(stdlib.h) 


setdisk 


(dir.h) 




getcurdir 


(dir.h) 


_splitpath 


(stdlib.h) 




getcwd 


(dir.h) 







EasyWin routines 



These routines are portable to EasyWin programs but are not available in 
Windows 16-bit programs. They are provided to ease porting of existing 
code into a Windows 16-bit application. 



clreol 

clrscr 

fgetchar 

getch 

getchar 



(conio.h) 
(conio.h) 
(stdio.h) 
(stdio.h) 
(stdio.h) 



getche 

gets 

gotoxy 

kbhit 

perror 



(stdio.h) 
(stdio.h) 
(conio.h) 
(conio.h) 
(errno.h) 
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print f 

putch 

putchar 

puts 

scanf 



(stdio.h) 
(conio.h) 
(stdio.h) 
(stdio.h) 
(stdio.h) 



vprintf 
vscanf 
zvherex 
wherey 



(stdio.h) 
(stdio.h) 
(conio.h) 
(conio.h) 



Inline routines 



These routines have inline versions. The compiler will generate code for the 
inline versions when you use #pragma intrinsic or if you specify program 
optimization. See the User's Guide for more details. 



abs 
alloca 
_crotl 
_crotr 
Jrotl 
Jrotr 
memchr 
memctnp 
memcpy 
memset 
_rotl 
rotr 



(math.h) 

(malloc.h) 

(stdlib.h) 

(stdlib.h) 

(stdlib.h) 

(stdlib.h) 

(mem.h) 

(mem.h) 

(mem.h) 

(mem.h) 

(stdlib.h) 

(stdlib.h) 



stpcpy 

strcat 

strchr 

strcmp 

strcpy 

strlen 

strncat 

strncmp 

strncpy 

strnset 

strrchr 

strset 



(string.h) 
(string.h) 
(string.h) 
(string.h) 
(string.h) 
(string.h) 
(string.h) 
(string.h) 
(string.h) 
(string.h) 
(string.h) 
(string.h) 



Input / output 
routines 



These routines provide stream- and operating-system level I/O capability. 



access 

_rtl_chmod 

chtnod 

chsize 

clearerr 

_rtl_close 

close 

_rtl_creat 

creat 

creatnew 

creattemp 

cscanf 

_dos_close 

_dos_creat 

_dos_creatnew 

_dos_getfileattr 

_dos_getftime 

_dos_open 

_dos_read 

_dos_setfileattr 

_dos_setftime 



(io.h) 

(io.h) 

(io.h) 

(io.h) 

(stdio.h) 

(io.h) 

(io.h) 

(io.h) 

(io.h) 

(io.h) 

(io.h) 

(conio.h) 

(dos.h) 

(dos.h) 

(dos.h) 

(dos.h) 

(dos.h) 

(dos.h) 

(dos.h) 

(dos.h) 

(dos.h) 



_dos_write 

dup 

dup2 

eof 

fclose 

fcloseall 

fdopen 

feof 

ferror 

fflush 

fgetc 

fgetchar 

fgetpos 

fgets 

filelength 

fileno 

flushall 

fopen 

fprintf 

fputc 

fputchar 



(dos.h) 

(io.h) 

(io.h) 

(io.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(io.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 
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fputs 


(stdio.h) 


putw 


(stdio.h) 


fread 


(stdio.h) 


_rtl_read 


(io.h) 


freopen 


(stdio.h) 


read 


(io.h) 


fscanf 


(stdio.h) 


remove 


(stdio.h) 


fseek 


(stdio.h) 


rename 


(stdio.h) 


fsetpos 


(stdio.h) 


rewind 


(stdio.h) 


Jsopen 


(stdio.h) 


rmtmp 


(stdio.h) 


fstat 


(sys\stat.h) 


scanf 


(stdio.h) 


ftell 


(stdio.h) 


setbuf 


(stdio.h) 


fwrite 


(stdio.h) 


setftime 


(io.h) 


getc 


(stdio.h) 


setmode 


(io.h) 


getch 


(conio.h) 


setvbuf 


(stdio.h) 


getchar 


(stdio.h) 


sopen 


(io.h) 


getche 


(conio.h) 


sprint f 


(stdio.h) 


getftime 


(io.h) 


sscanf 


(stdio.h) 


gets 


(stdio.h) 


_strerror 


(string.h, stdio.h) 


getw 


(stdio.h) 


strerror 


(stdio.h) 


ioctl 


(io.h) 


tell 


(io.h) 


isatty 


(io.h) 


tempnam 


(stdio.h) 


kbhit 


(conio.h) 


TFile 


(file.h) 


lock 


(io.h) 


tmpfile 


(stdio.h) 


locking 


(io.h) 


tmpnam 


(stdio.h) 


Iseek 


(io.h) 


umask 


(io.h) 


_rtl_open 


(io.h) 


unlink 


(dos.h) 


open 


(io.h) 


unlock 


(io.h) 


jpclose 


(stdio.h) 


utime 


(utime. h) 


perror 


(stdio.h) 


vfprintf 


(stdio.h) 


_pipe 


(io.h) 


vfscanf 


(stdio.h) 


jpopen 


(stdio.h) 


vprintf 


(stdio.h) 


printf 


(stdio.h) 


vscanf 


(stdio.h) 


pule 


(stdio.h) 


vsprintf 


(stdio.h) 


putchar 


(stdio.h) 


vsscanf 


(io.h) 


puts 


(stdio.h) 
provide operating-syst 


_rtl_write 
em BIOS and ma 


(io.h) 


... .. These routines 
Interface routines , .,. . 


chine-specific 


capabilities. 








bdos 


(dos.h) 


dosexterr 


(dos.h) 


bdosptr 


(dos.h) 


_dos_getvect 


(dos.h) 


biosequip 


(bios.h) 


_dos_setvect 


(dos.h) 


_bios_equiplist 


(bios.h) 


_enable 


(dos.h) 


biosmemory 


(bios.h) 


enable 


(dos.h) 


biostime 


(bios.h) 


FP_OFF 


(dos.h) 


_chain_intr 


(dos.h) 


FP_SEG 


(dos.h) 


country 


(dos.h) 


geninterrupt 


(dos.h) 


ctrlbrk 


(dos.h) 


getcbrk 


(dos.h) 


_disable 


(dos.h) 


getdfree 


(dos.h) 


disable 


(dos.h) 


getdta 


(dos.h) 
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getfat 

getfatd 

getpsp 

getvect 

getverify 

inp 

inpw 

inport 

inportb 

int86 

int86x 

intdos 

intdosx 

intr 

MKJFP 

outp 



(dos.h) 

(dos.h) 

(dos.h) 

(dos.h) 

(dos.h) 

(conio.h 

(conio.h 

(dos.h) 

(dos.h) 

(dos.h) 

(dos.h) 

(dos.h) 

(dos.h) 

(dos.h) 

(dos.h) 

(conio.h) 



outpw 


(conio.h) 


outport 


(dos.h) 


outportb 


(dos.h) 


parsfnm 


(dos.h) 


peek 


(dos.h) 


peekb 


(dos.h) 


poke 


(dos.h) 


pokeb 


(dos.h) 


segread 


(dos.h) 


setcbrk 


(dos.h) 


_setcursortype 


(conio.h) 


setdta 


(dos.h) 


setvect 


(dos.h) 


setverify 


(dos.h) 


sleep 


(dos.h) 



International 
locale API 
routines 



These routines are affected by the current locale. The current locale is 
specified by the setlocale function and is enabled by defining 

_ _USELOCALES with -D command line option. When you define 

_ _USELOC ALES , only function versions of the following routines are 

used in the run-time library rather than macros. See online Help for a 
discussion of the International API. 



cprintf 

cscanf 

fprintf. 

fscanf 

isalnum 

isalpha 

iscntrl 

isdigit 

isgraph 

[slower 

isprint 

ispunct 

isspace 

isupper 

isxdigit 

localeconv 

print f 



(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(ctype.h) 

(ctype.h) 

(ctype.h) 

(ctype.h) 

(ctype.h) 

(ctype.h) 

(ctype.h) 

(ctype.h) 

(ctype.h) 

(ctype.h) 

(ctype.h) 

(locale.h) 

(stdio.h) 



scanf 

setlocale 

sprint f 

sscanf 

strcoll 

strftime 

strlwr, _fstrlwr 

strupr, jstrupr 

strxfrm 

tolower 

toupper 

vfprintf 

vfscanf 

vprintf 

vscanf 

vsprintf 

vsscanf 



(stdio.h) 

(locale.h) 

(stdio.h) 

(stdio.h) 

(string.h) 

(time.h) 

(string.h) 

(string .h) 

(string.h) 

(ctype.h) 

(ctype.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 

(stdio.h) 



Manipulation 
routines 



These routines handle strings and blocks of memory: copying, comparing, 
converting, and searching. 



mblen 
mbstowcs 



(stdlib.h) 
(stdlib.h) 



mbtowc 
memccpy 



(stdlib.h) 
(mem.h, string.h) 
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memchr 

memcmp 

memcpy 

memicmp 

memmove 

memset 

movedata 

movmem 

setmem 

stpcpy 

strcat 

strchr 

strcmp 

strcmpi 

strcoll 

strcpy 

strcspn 

strdup 

strerror 

stricmp 



mem 

mem 

mem 

mem 

mem 

mem 

mem 

mem 

mem 

string.h) 

string.h) 

string.h) 

string.h) 

string.h) 

string.h) 

string.h) 

string.h) 

string.h) 

string.h) 

string.h) 



,h, string.h) 
,h, string.h) 
.h, string.h) 
,h, string.h) 
,h, string.h) 
.h, string.h) 
,h, string.h) 
,h, string.h) 
.h) 



string 

strlen 

strlwr 

strncat 

strncmp 

strncmpi 

strncpy 

strnicmp 

strnset 

strpbrk 

strrchr 

strrev 

strset 

strspn 

strstr 

strtok 

strupr 

strxfrm 

wcstombs 

wctomb 



(cstring.h) 

(string.h) 

(string.h) 

(string.h) 

(string.h) 

(string.h) 

(string.h) 

(string.h) 

(string.h) 

(string.h) 

(string.h) 

(string.h) 

(string.h) 

(string.h) 

(string.h) 

(string.h) 

(string.h) 

(string.h) 

(stdlib.h) 

(stdlib.h) 



Math routines 



These routines perform mathematical calculations and conversions. 



abs 

acos 

acosl 

arg 

asin 

asinl 

atari 

atari! 

atanll 

atanl 

at of 

atoi 

atol 

_atold 

bed 

cabs 

cabsl 

ceil 

ceill 

_clear87 

complex 

conj 

_control87 

cos 

cosh 



(complex 

(complex 

(math.h) 

(complex 

(complex 

(math.h) 

(complex 

(complex 

(math.h) 

(math.h) 

(stdlib.h, 

(stdlib.h) 

(stdlib.h) 

(math.h) 

(bcd.h) 

(math.h) 

(math.h) 

(math.h) 

(math.h) 

(floath) 

(complex 

(complex 

(floath) 

(complex 

(complex 



h, stdlib.h) 
h, math.h) 

h) 

h, math.h) 

h, math.h) 
h, math.h) 



math.h) 



h) 
h) 

h, math.h) 
h, math.h) 



coshl 


(math.h) 


cosl 


(math.h) 


div 


(math.h) 


ecvt 


(stdlib.h) 


exp 


(complex.h, math.h) 


expl 


(math.h) 


fabs 


(math.h) 


fabsl 


(math.h) 


fevt 


(stdlib.h) 


floor 


(math.h) 


floorl 


(math.h) 


fmod 


(math.h) 


fmodl 


(math.h) 


Jpreset 


(floath) 


frexp 


(math.h) 


frexpl 


(math.h) 


gcvt 


(stdlib.h) 


hypot 


(math.h) 


hypotl 


(math.h) 


imag 


(complex.h) 


itoa 


(stdlib.h) 


labs 


(stdlib.h) 


Idexp 


(math.h) 


Idexpl 


(math.h) 


Idiv 


(math.h) 
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log (complex.h, math.h) 

logl (math.h) 

loglO (complex.h, math.h) 

loglOl (math.h) 

Jrotl (stdlib.h) 

Jrotr (stdlib.h) 

Uoa (stdlib.h) 

jnatherr (math.h) 

jnatherrl (math.h) 

modf (math.h) 

tnodfl (math.h) 

norm (complex.h) 

polar (complex.h) 

poly (math.h) 

polyl (math.h) 

pow (complex.h, math.h) 

powlO (math.h) 

powlOl (math.h) 

powl (math.h) 

rand (stdlib.h) 

random (stdlib.h) 



randomize 

real 

_rotl 

_rotr 

sin 

sink 

sinhl 

sinl 

sqrt 

sqrtl 

srand 

_status87 

strtod 

strtol 

_strtold 

strtoul 

tan 

tank 

tanhl 

tanl 

ultoa 



(stdlib.h) 

(complex.h) 

(stdlib.h) 

(stdlib.h) 

(complex.h, math.h) 

(complex.h, math.h) 

(math.h) 

(math.h) .h, math.h) 

(complex.h, math.h) 

(math.h) 

(stdlib.h) 

(float.h) 

(stdlib.h) 

(stdlib.h) 

(stdlib.h) 

(stdlib.h) 

(complex.h, math.h) 

(complex.h, math.h) 

(complex.h, math.h) 

(math.h) 

(stdlib.h) 



Memory routines 


These routines provide dynamic 
large-data models. 


memory allocation in the small-data a 




alloca 


(malloc.h) 


heapcheckfree (alloch) 




Jbiosjnemsize 


(bios.h) 


heapchecknode (alloch) 




calloc 


(alloch, stdlib.h) 


heapwalk (alloch) 




farcalloc 


(alloch) 


malloc (alloch, stdlib.h) 




farfree 


(alloch) 


realloc (alloch, stdlib.h) 




farmalloc 


(alloch) 


set_new_handler (new.h) 




free 


(alloch, stdlib.h) 


stackavail (malloc.h) 




heapcheck 
These routines 


(alloch) 
provide nonlocal 




Miscellaneous 


goto capabilities and locale. 


routines 










localeconv 


(locale.h) 


setjmp (setjmp.h) 




longjmp 


(setjmp.h) 


setlocale (localch) 



Obsolete 
definitions 



The following global variables have been renamed to comply with ANSI 
naming requirements. You should always use the new names. If you link 
with libraries that were compiled with Borland C++ 3.1 (or earlier) header 
files, you will get the message 



Error: undefined external varname in module LIBNAME.LIB 
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Table 1.4 

Obsolete global 

variables 



A library module that results in such an error should be recompiled. How- 
ever, if you cannot recompile the code for such libraries, you can link with 
OBSOLETE.LIB to resolve the external variable names. 

The following global variables have been renamed: 



Old name 



New name 



Header file 



daylight 


_daylight 


time.h 


directvideo 


directvideo 


conio.h 


environ 


environ 


' stdlib.h 


sys_errlist 


_sys_errlist 


errno.h 


sys_nerr 


_sys_nerr 


errno.h 


timezone 


timezone 


time.h 


tzname 


tzname 


time.h 



The old names of the following functions are available. However, the 
compiler will generate a warning that you are using an obsolete name. 
Future versions of Borland C++ might not provide support for the old 
function names. 

The following function names have been changed: 



Table 1.5 


Old name 


New name 




Header file 


Obsolete function 






















names 


_chmod 


_rtl_chmod 




io.h 






_close 


_rtl_close 




io.h 






_creat 


_rtl_creat 




io.h 






_heapwalk 


_rtl_heapwalk 




malloc.h 




_open 


_rtl_open 




io.h 






jead 


jtljead 




io.h 






_write 


_rtl_write 




io.h 






These routines invoke and terminate 


new processes i 




Process control 


"rom within another 


routines 


routine. 












abort 


(process.h) 


execve 




(process.h) 




Jbeginthread 


(process.h) 


execvp 




(process.h) 




JbeginthreadNT 


(process.h) 


execvpe 




(process.h) 




_c_exit 


(process.h) 


_exit 




(process.h) 




_cexit 


(process.h) 


exit 




(process.h) 




cwait 


(process.h) 


_expand 




(process.h) 




_endthread 


(process.h) 


getpid 




(process.h) 




execl 


(process.h) 


_pclose 




(stdio.h) 




execle 


(process.h) 


jpopen 




(stdio.h) 




execlp 


(process.h) 


raise 




(signal.h) 




execlpe 


(process.h) 


signal 




(signal.h) 




execv 


(process.h) 


spawnl 




(process.h) 
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spawnle 
spawnlp 
spawnlpe 
spawnv 



(process.h) 
(process.h) 
(process.h) 
(process.h) 



spawnve 


(process.h) 


spawnvp 


(process.h) 


spawnvpe 


(process.h) 


wait . 


(process.h) 



Time and date 


These are time conversion an 


routines 








asctime 


(time.h) 




_bios_timeofday 
dime 


(bios.h) 
(time.h) 




difftime 
_dos_getdate 
_dos_gettime 
_dos_setdate 


(time.h) 
(dos.h) 
(dos.h) 
(dos.h) 




_dos_settime 


(dos.h) 




dostounix 


(dos.h) 




ftime 

getdate 

gettime 


(sys\timeb.h) 

(dos.h) 

(dos.h) 



gmtime 


time.h) 


localtime 


time.h) 


mktime 


time.h) 


stime 


time.h) 


_strdate 


time.h) 


strftime 


time.h) 


_strtime 


time.h) 


TDate 


(date.h) 


time 


time.h) 


TTime 


time.h) 


tzset 


time.h) 


unixtodos 


'dos.h) 



Variable argument 
list routines 



These routines are for use when accessing variable argument lists (such as 
with printf, vprintf, vscanf, and so on). 



va_arg 
va end 



(stdarg.h) 
(stdarg.h) 



va start 



(stdarg.h) 
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The main function 



See the 

Programmer's Guide, 

Chapter 8, for a 

discussion of 

Windows 

programming. 



Every C and C++ program must have a program-startup function. 
Console-based programs call the main function at startup. Windows GUI 
programs call the WinMain function at startup. Where you place the startup 
function is a matter of preference. Some programmers place main at the 
beginning of the file, others at the end. Regardless of its location, the fol- 
lowing points about main always apply. 



Arguments to main 



Three parameters (arguments) are passed to main by the Borland C++ 
startup routine: argc, argv, and env. 

m argc, an integer, is the number of command-line arguments passed to 
main, including the name of the executable itself. 

■ argv is an array of pointers to strings (char *[]). 

• argv[0] is the full path name of the program being run. 

• argv [1] points to the first string typed on the operating system 
command line after the program name. 

• argv[2] points to the second string typed after the program name. 

• argv[argc-l] points to the last argument passed to main. 

• argv[argc] contains NULL. „ 

■ env is also an array of pointers to strings. Each element of env[] holds a 
string of the form ENWAR= value. 

• ENVVAR is the name of an environment variable, such as PATH or 
COMSPEC. 

• value is the value to which ENVVAR is set, such as C:\APPS;C:\ 
TOOLS; (for PATH) or C:\DOS\COMMAND.COM (for COMSPEC). 
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Refer to the getenv 

and putenv entries in 

Chapter 3, and the 

environ entry in 

Chapter 4 for more 

information. 



If you declare any of these parameters, you must declare them exactly in the 
order given: argc, argv, env. For example, the following are all valid 
declarations of main's arguments: 



int main() 

int main (int argc) 

int main (int argc, char * argv[] 

int main (int argc, char * argv[] 



/* legal but very unlikely */ 



char 



The declaration int main (int argc) is legal, but it's very unlikely that you 
would use argc in your program without also using the elements of argv. 

The argument env is also available through the global variable _environ. 

For all platforms, argc and argv are also available via the global variables 
_argc and _argv. 



Examining 
arguments to 
main 



Here is an example that demonstrates a simple way of using these 
arguments passed to main: 

I* Program ARGS.C */ 
#include <stdio.h> 
ttinclude <stdlib.h> 

int main (int argc, char *argv[], char *env[]) { 
int i; 

printf ("The value of argc is Id \n\n", argc); 
printf ("These are the %d command-line arguments passed to" 
" main:\n\n", argc) ; 

for (i = 0; i < argc; i++) 

printf (" argv[%d]: %s\n", i, argv[i]); 

printf ("\nThe environment string(s) on this system are:\n\n"); 

for. (i = 0; env[i] != NULL; i++) 

printf (" env[%d]: %s\n", i, env[i]); 
return 0; 
} 

Suppose you run ARGS.EXE at the command prompt with the following 
command line: 

C:> args first_arg "arg with blanks" 3 4 "last but one" stop! 

Note that you can pass arguments with embedded blanks by surrounding 
them with quotes, as shown by "argument with blanks" and "last but one" 
in this example command line. 

The output of ARGS.EXE (assuming that the environment variables are set 
as shown here) would then be like this: 
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The value of argc is 7 

These are the 7 command-line arguments passed to main: 



argv[0] 


C:\BC4\ARGS.EXE 


argv[l] 


first_arg 


argv[2] 


arg with blanks 


argv[3] 


3 


argv[4] 


4 


argv[5] 


last but one 


argv [ 6 ] 


stop! 




Wildcard 
arguments 



Wildcard arguments 

are used only in 

console-mode 

applications. 



Linking with 
WILDARGS.OBJ 



The environment string (s) on this system are 

env[0]: C0MSPEC=C:\C0MMAND.C0M 

env[l] : PR0MPT=$p $g 

env[2]: PATH=C:\SPRINT;C:\D0S;C:\BC4 

The maximum combined length of the command-line arguments passed to 
main (including the space between adjacent arguments and the program 
name itself) is 255; this is a Win32 limit. 

Command-line arguments containing wildcard characters can be expanded 
to all the matching file names, much the same way DOS expands wildcards 
when used with commands like COPY. All you have to do to get wildcard 
expansion is to link your program with the WILDARGS.OBJ object file, 
which is included with Borland C++. 

Once WILDARGS.OBJ is linked into your program code, you can send 
wildcard arguments of the type *.* to your main function. The argument 
will be expanded (in the argv array) to all files matching the wildcard mask. 
The maximum size of the argv array varies, depending on the amount of 
memory available in your heap. 

If no matching files are found, the argument is passed unchanged. (That is, 
a string consisting of the wildcard mask is passed to main.) 

Arguments enclosed in quotes ("...") are not expanded. 

The following commands compile the file ARGS.C and link it with the 
wildcard expansion module WILDARGS.OBJ, then run the resulting 
executable file ARGS.EXE: 

BCC ARGS.C WILDARGS.OBJ 
ARGS C:\BC4\INCLUDE\*.H "*.C" 

When you run ARGS.EXE, the first argument is expanded to the names of 
all the *.H files in your Borland C++ INCLUDE directory. Note that the 
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expanded argument strings include the entire path. The argument *.C is not 
expanded because it is enclosed in quotes. 

In the IDE, simply specify a project file (from the project menu) that 
contains the following lines: 

ARGS 
WILDARGS.OBJ 

If you prefer the wildcard expansion to be the default, modify your 
standard CW327.LIB library files to have WILDARGS.OBJ linked automati- 
cally. To accomplish that, remove SETARGV and INITARGS from the 
libraries and add WILD ARGS. The following commands invoke the Turbo 
librarian (TLIB) to modify all the standard library files (assuming the 
current directory contains the standard C and C++ libraries and 
WILDARGS.OBJ): 

tlib CW32 -setargv +wildargs 
tlib CW32MT -setargv +wildargs 
tlib -setargv +wildargs 



Using -p (Pascal calling conventions) 




If you compile your program using Pascal calling conventions (described in 
the Programmer's Guide, Chapter 2), you must remember to explicitly 
declare main as a C type. Do this with the _ _cdecl keyword, like this: 

int cdecl main(int argc, char* argv[], char* envp[]) 

The value main returns 

The value returned by main is the status code of the program: an int. How- 
ever, if your program uses the routine exit (or _exit) to terminate, the value 
returned by main is the argument passed to the call to exit (or to _exit). 

For example, if your program contains the call exit (1), the. status is 1. 

Passing file information to child processes 

If your program uses the exec or spawn functions to create a new 
process, the new process will normally inherit all of the open file handles 
created by the original process. However, some information about these 
handles will be lost, including the access mode used to open the file. For 
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example, if your program opens a file for read-only access in binary mode, 
and then spawns a child process, the child process might corrupt the file by 
writing to it, or by reading from it in text mode. 

To allow child processes to inherit such information about open files, you 
must link your program with the object file FILEINFO.OBJ. For example: 

BCC32 TEST.C \BC4\LIB\FILEINFO.0BJ 

The file information is passed in the environment variable _C_FILE_INFO. 
This variable contains encoded binary information, and your program 
should not attempt to read or modify its value. The child program must 
have been built with the C++ run-time library to inherit this information 
correctly. Other programs can ignore _C_FILE_INFO, and will not inherit 
file information. 



Multithread programs 




See the online Help 

example for 

_beginthread\o see 

how to use these 

functions and 

Jhreadid'ma 

program. 



32-bit programs can create more than one thread of execution. If your 
program creates multiple threads, and these threads also use the C++ run- 
time library, you must use the CW32MT.LIB or CW32MTI library instead. 

The multithread libraries provide the Jbeginthread and _beginthreadNT 
functions, which you use to create threads. The multithread libraries also 
provide the _endthread function, which terminates threads, and the global 
variable _threadid. This global variable contains the current thread's 
identification number (also known as the thread ID). The header file 
stddef .h contains the declaration of Jhreadid. 

When you compile or link a program that uses multiple threads, you must 
use the -WM compiler switch. For example: 

BCC32 -WM THREAD. C 

Special care must be taken when using the signal function in a multithread 
program. See the description of the signal function for more information. 
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Run-time functions 



Programming 

examples for each 

function are available 

in the online Help 

system. You can 

easily copy them from 

Help and paste them 

into your files. 



This chapter contains a detailed description of each function in the Borland 
C++ library. The functions are listed in alphabetical order, although a few 
of the routines are grouped by "family" (the exec. . . and spawn.. . functions, 
for example) because they perform similar or related tasks. 

Each function entry provides certain standard information. For instance, 
the entry for free 

■ Tells you which header file(s) contains the prototype for free. 
u Summarizes what free does. 

■ Gives the syntax for calling free. 

■ Gives a detailed description of how free is implemented and how it 
relates to the other memory-allocation routines. 

■ Lists other language compilers that include similar functions. 

■ Refers you to related Borland C++ functions. 

The following sample library entry lists each entry section and describes 
the information it contains. The alphabetical listings start on page 27. 



Sample function entry 



header file name 



Function 
Syntax 



The function is followed by the header file(s) containing the prototype for 
function or definitions of constants, enumerated types, and so on used by 
function. 

Summary of what this function does. 

function (modifier parameter!, ...]);■ 

This gives you the declaration syntax for function; parameter names are 
italicized. The [,...] indicates that other parameters and their modifiers can 
follow. 

Portability is indicated by marks (■) in the columns of the portability table. 
A sample portability table is shown here: 
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Sample function entry 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 

















Each entry in the portability table is described in the following table. Any 
additional restrictions are discussed in the Remarks section. 



Remarks 
Return value 
See also 

Example 



DOS Available for DOS. 

UNIX . Available under UNIX andfcr POSIX. 

Win 1 6 Compatible with 1 6-bit Windows programs running on Microsoft Windows 3.1 , Windows 
for Workgroups 3.1 , and Windows for Workgroups 3.1 1 . EasyWin users should see the 
Users Guide for information about using certain non-Windows functions (such as printf 
and scant) in programs that run under Windows. 

Win 3 2 Available to 32-bit Windows programs running on Win32s 1 .0, and Windows NT 3.1 
applications. 

ANSI C Defined by the ANSI C Standard. 

ANSI C++ Included in the ANSI C++ proposal. 

OS/2 Available for OS/2. 

If more than one function is discussed and their portability features are 
identical, only one row is used. Otherwise, each function is represented in a 
separate row. 

This section describes what function does, the parameters it takes, and any 
details you need to use function and the related routines listed. 

The value that function returns (if any) is given here. It function sets any 
global variables, their values are also listed. 

Routines related to function that you might want to read about are listed 
here. If a routine name contains an ellipsis, it indicates that you should refer 
to a family of functions (for example, exec. . . refers to the entire family of 
exec functions: execl, execle, execlp, execlpe, execv, execve, execvp, and execvpe). 

The function examples have been moved into online Help so that you can 
easily cut-and-paste them to your own applications. 
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abort 




abort 



stdlib.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Abnormally terminates a program. 

void abort (void) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


" 


■ 


■ 


' 


■ 



abort causes an abnormal program termination by calling rafse(SIGABRT). If 
there is no signal handler for SIGABRT, then abort writes a termination 
message ("Abnormal program termination") on stderr, then aborts the 
program by a call to _exit with exit code 3. 

abort returns the exit code 3 to the parent process or to the operating system 
command processor. 

assert, atexit, _exit, exit, raise, signal, spawn.. . 



abs 



stdlib.h 



Function 
Syntax 

Remarks 



Return value 



See also 



Returns the absolute value of an integer. 



int abs(int x) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


" 


■ 



abs returns the absolute value of the integer argument x. If abs is called 
when stdlib.h has been included, it's treated as a macro that expands to 
inline code. 

If you want to use the abs function instead of the macro, include ttundef abs 
in your program, after the ttinclude <stdlib.h>. 

This function can be used with bed and complex types. 

The abs function returns an integer in the range of to INT_MAX, with the 
exception that an argument with the value INTJVIIN is returned as 
INT_MIN. The values for INT_MAX and INTJVIIN are defined in header 
file limits.h. 

bed, cabs, complex, jabs, labs 
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access 



access 



io.h 



Function 
Syntax 



Remarks 



Determines accessibility of a file. 

int access (const char *filename, int amode); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 






■ 



access checks the file named by filename to determine if it exists, and 
whether it can be read, written to, or executed. 

The list of amode values is as follows: 



Return value 



06 Check for read and write permission 

04 Check for read permission 

02 Check for write permission 

01 Execute (ignored) 

00 Check for existence of file 

Under DOS, OS/2, and Windows (16- and 32-bit) all existing files have read 
access (amode equals 04), so 00 and 04 give the same result. Similarly, amode 
values of 06 and 02 are equivalent because under DOS write access implies 
read access. 

If filename refers to a directory, access simply determines whether the 
directory exists. 

If the requested access is allowed, access returns 0; otherwise, it returns a 
value of -1, and the global variable errno is set to one of the following 
values: 



See also 



EACCES Permission denied 
ENOENT Path or file name not found 

chmod, fstat, stat 



acos, acosl 



math.h 



Function 



Calculates the arc cosine. 
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Syntax 



Remarks 



acos 
acosl 



Return value 



See also 



acos, acosl 




double acos (double x) ; 

long double acosl (long double x) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 


■ 




■ 


■ 






■ 



acos returns the arc cosine of the input value, acosl is the long double 
version; it takes a long double argument and returns a long double result. 
Arguments to acos and acosl must be in the range -1 to 1, or else acos and 
acosl return NAN and set the global variable errno to 

EDOM Domain error 

This function can be used with bed and complex types. 

acos and acosl of an argument between -1 and +1 return a value in the range 
to pi. Error handling for these routines can be modified through the 
functions jnatherr and jnatherrl. 

asin, atari, atanl, bed, complex, cos, jnatherr, sin, tan 



alloca 



malloc.h 



Function 
Syntax 



Remarks 



Allocates temporary stack space. 

void *alloca(size_t size); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 






■ 



alloca allocates size bytes on the stack; the allocated space is automatically 
freed up when the calling function exits. 

Because alloca modifies the stack pointer, do not place calls to alloca in an 
expression that is an argument to a function. 

The alloca function should not be used in the try 7 block of a C++ program. If 
an exception is thrown any values placed on the stack by alloca will be 
corrupted. 

If the calling function does not contain any references to local variables in 
the stack, the stack will not be restored correctly when the function exits, 
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alloca 



resulting in a program crash. To ensure that the stack is restored correctly, 
use the following code in the calling function: 

char *p; 

char dummy [5] ; 

dummy [0] = 0; 



Return value 
See also 



p = alloca (nbytes) ; 

If enough stack space is available, alloca returns a pointer to the allocated 
stack area. Otherwise, it returns NULL. 

malloc 



asctime 



time.h 



Function 
Syntax 



Remarks 



Return value 



See also 



Converts date and time to ASCII. 

char *asctime (const struct tm *tblock) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 



asctime converts a time stored as a structure in *tblock to a 26-character 
string of the same form as the ctime string: 

Sun Sep 16 01:03:52 1973\n\0 

asctime returns a pointer to the character string containing the date and 
time. This string is a static variable that is overwritten with each call to 
asctime. 

ctime, dif f time ,f time, gmtime, localtime, mktime, strftime, stime, time, tzset 



asin, asinl 



math.h 



Function 
Syntax 



asm 
asinl 



Calculates the arc sine. 

double asin(double x) ; 

long double asinl (long double x) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 


■ 




■ 


■ 






■ 
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Remarks 



Return value 



See also 



asin, asinl 



asin of a real argument returns the arc sine of the input value, sinl is the 
long double version; it takes a long double argument and returns a long 
double result. 

Real arguments to asin and asinl must be in the range -1 to 1, or else asin 
and asinl return NAN and set the global variable errno to 

EDOM Domain error 

This function can be used with bed and complex types. 

asin and asinl of a real argument return a value in the range -pi/2 to pi/2. 
Error handling for these functions can be modified through the functions 
jnatherr and jnatherrl. 

acos, atan, atanl, bed, complex, cos, jnatherr, sin, tan 




assert 



asserth 



Function 
Syntax 



Remarks 



Return value 
See also 



Tests a condition and possibly aborts. 

void assert (int test); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 



assert is a macro that expands to an if statement; if test evaluates to zero, 
assert prints a message on stderr and aborts the program (by calling abort). 

assert displays this message: 

Assertion failed: test, file filename, line linenum 

The filename and linenum listed in the message are the source file name and 
line number where the assert macro appears. 

If you place the #def ine NDEBUG directive ("no debugging") in the source 
code before the ttinclude <assert.h> directive, the effect is to comment out 
the assert statement. 

None. 

abort 



atan, atanl 



math.h 



Function 



Calculates the arc tangent. 
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atan, atanl 



Syntax 



Remarks 



Return value 



See also 



atan 
atanl 



double atan (double x) ; 

long double atanl (long double x) 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


' 


■ 


■ 


■ 


■ 


■ 


■ 




■ 


■ 






■ 



atan calculates the arc tangent of the input value. 

atanl is the long double version; it takes a long double argument and 
returns a long double result. This function can be used with bed and complex 
types. 

atan and atanl of a real argument return a value in the range -pi/ "1 to pi/ 2. 
Error handling for these functions can be modified through the functions 
jnatherr and jnatherrl. 

acos, asin, atanl, bed, complex, cos, jnatherr, sin, tan 



atan2, atan2l 



math.h 



Function 
Syntax 



Remarks 



atan2 
atan2l 



Return value 



See also 



Calculates the arc tangent of y/x. 

double atan2 (double y, double x) ; 

long double atan21(long double y, long double x) 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 


■ 




■ 


■ 






■ 



atanl returns the arc tangent of y/x; it produces correct results even when 
the resulting angle is near pi/ 2 or -pi/ 2 (x near 0). If both x and y are set to 
0, the function sets the global variable errno to EDOM, indicating a domain 
error. 

atanll is the long double version; it takes long double arguments and 
returns a long double result. 

atanl and atanll return a value in the range -pi to pi. Error handling for 
these functions can be modified through the functions jnatherr and 
jnatherrl. 

acos, asin, atan, cos, jnatherr, sin, tan 
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atexit 



atexit 



stdlib.h 




Function 
Syntax 



Remarks 



Return value 
See also 



Registers termination function. 

int atexit (void (JJSERENTRY * func) (void) ) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 


■ 


■ 


■ 



atexit registers the function pointed to by func as an exit function. Upon 
normal termination of the program, exit calls func just before returning to 
the operating system, func must be used with the _USERENTRY calling 
convention. 

Each call to atexit registers another exit function. Up to 32 functions can be 
registered. They are executed on a last-in, first-out basis (that is, the last 
function registered is the first to be executed). 

atexit returns on success and nonzero on failure (no space left to register 
the function). 

abort, _exit, exit, spawn.. . 



atof, atold 



math.h 



Function 
Syntax 



Remarks 



atof 
atold 



Converts a string to a floating-point number. 

double atof (const char *s) ; 

long double _atold(const char *s); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 


■ 




■ 


■ 






■ 



atof converts a string pointed to by s to double; this function recognizes the 
character representation of a floating-point number, made up of the 
following: 

■ An optional string of tabs and spaces 

■ An optional sign 

■ A string of digits and an optional decimal point (the digits can be on both 
sides of the decimal point) 

■ An optional e or E followed by an optional signed integer 
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atof , _atold 



Return value 



See also 



The characters must match this generic format: 

[zvhitespace] [sign] [ddd] [.] [ddd] [e I E[sign]ddd] 

atof also recognizes +INF and -INF for plus and minus infinity, and +NAN 
and -NAN for Not-a-Number. 

In this function, the first unrecognized character ends the conversion. 

_atold is the long double version; it converts the string pointed to by s to a 
long double. 

strtod and _strtold are similar to atof and _atold; they provide better error 
detection, and hence are preferred in some applications. 

atof and _atold return the converted value of the input string. 

If there is an overflow, atof (or jitold) returns plus or minus HUGE_VAL (or 
_LHUGE_VAL), errno is set to ERANGE (Result out of range), and jnatherr 
(or jnatherrl) is not called. 

atoi, atol, ecvt, fcvt, gcvt, scanf, strtod 



atoi 



stdlib.h 



Function 
Syntax 



Remarks 



Converts a string to an integer. 

int atoi (const char *s); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 



atoi converts a string pointed to by s to int; atoi recognizes (in the following 
order) 

■ An optional string of tabs and spaces 

■ An optional sign 

■ A string of digits 

The characters must match this generic format: 



Return value 



[ws] [sn] [ddd] 

In this function, the first unrecognized character ends the conversion. There 
are no provisions for overflow in atoi (results are undefined). 

atoi returns the converted value of the input string. If the string cannot be 
converted to a number of the corresponding type (int), atoi returns 0. 
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atoi 



See also 

atol 



atof, atol, ecvt, fcvt, gcvt, scanf, strtod 




stdlib.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Converts a string to a long. 

long atol (const char *s); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


, ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 



atol converts the string pointed to by s to long, atol recognizes (in the 
following order) 

■ An optional string of tabs and spaces 

■ An optional sign 

■ A string of digits 

The characters must match this generic format: 

[ws] [sn] [ddd] 

In this function, the first unrecognized character ends the conversion. There 
are no provisions for overflow in atol (results are undefined). 

atol returns the converted value of the input string. If the string cannot be 
converted to a number of the corresponding type (long), atol returns 0. 

atof, atoi, ecvt, fcvt, gcvt, scanf, strtod, strtol, strtoul 



atold 



bdos 



See atof. 



dos.h 



Function 
Syntax 



Accesses DOS system calls. 

int bdos(int dosfun", unsigned dosdx, unsigned dosal); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 
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bdos 



Remarks 



Return value 
See also 



bdos provides direct access to many of the DOS system calls. See your DOS 
reference manuals for details on each system call. 

For system calls that require ah integer argument, use bdos; if they require a 
pointer argument, use bdosptr. In the large data models (compact, large, and 
huge), it is important to use bdosptr instead of bdos for system calls that 
require a pointer as the call argument. 

dosfun is defined in your DOS reference manuals. 

dosdx is the value of register DX. 

dosal is the value of register AL. 

The return value of bdos is the value of AX set by the system call. 

bdosptr, geninterrupt, int86, int86x, intdos, intdosx 



bdosptr 



dos.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Accesses DOS system calls. 

int bdosptr(int dosfun, void *argument, unsigned dosal); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 











bdosptr provides direct access to many of the DOS system calls. See your 
DOS reference manuals for details of each system call. 

For system calls that require an integer argument, use bdos; if calls require a 
pointer argument, use bdosptr. In the large data models (compact, large, and 
huge), it is important to use bdosptr for system calls that require a pointer as 
the call argument. In the small data models, the argument parameter to 
bdosptr specifies DX; in the large data models, it gives the DS:DX values to 
be used by the system call. 

dosfun is defined in your DOS reference manuals, dosal is the value of 
register AL. 

The return value of bdosptr is the value of AX on success or -1 on failure. 
On failure, the global variables errno and _doserrno are set. 

bdos, geninterrupt, int86, int86x, intdos, intdosx 
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_beginthread 



_beginthread 



process.h 




Function 
Syntax 



Remarks 



Return value 



Starts execution of a new thread. 

unsigned long _beginthread (JJSERENTRY (*start_address) (void *) 

unsigned stack_size, void *arglist) 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 








■ 






■ 



The Jbeginthread function creates and starts a new thread. The thread starts 
execution at start jiddr ess. (Note that start _address must be declared to be 
JJSERENTRY. )The size of its stack in bytes is stack_size; the stack is 
allocated by the operating system after the stack size is rounded up to the 
next multiple of 4096. The thread is passed arglist as its only parameter; it 
can be NULL, but must be present. The thread terminates by simply 
returning, or by calling _endthread. 

Either this function or _beginthreadNT must be used instead of the operating 
system thread-creation API function because Jbeginthread and 
JbeginthreadNT perform initialization required for correct operation of the 
run-time library functions. 

This function is available only in the multithread libraries. 

The function is also available for OS/2. However, under OS/2 the function 
returns and int and does not require JJSERENTRY. 

Jeginthread returns the handle of the new thread. In the event of an error, 
the function returns -1, and the global variable errno is set to one of the 
following values: 



See also 



EAGAIN 
EINVAL 



Too many threads 
Invalid request 



See also the Win32 description of GetLastError. 
JbeginthreadNT, _endthread 



_beginthreadNT 



process.h 



Function 



Starts execution of a new thread under Windows NT. 
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_beginthreadNT 



Syntax 



Remarks 



Return value 



unsigned long _beginthreadNT(void (JJSERENTRY *start_address) (void *), 

unsigned stack_size, void *arglist, 
void *security_attrib, unsigned long create_flags, 
unsigned long *thread_id) ; 



DOS 


UNIX 


Win 16 . 


Win 32 


ANSI C 


ANSI C++ 


OS/2 








■ 









All multithread Windows NT programs must use JbeginthreadNT or the 
Jbeginthread function instead of the operating system thread-creation API 
function because Jbeginthread and JbeginthreadNT perform initialization 
required for correct operation of the run-time library functions. The 
JbeginthreadNT function provides support for the operating system 
security. These functions are available only in the multithread libraries. 

The JbeginthreadNT function creates and starts a new thread. The thread 
starts execution at start _addr ess. (Note that start _address must be declared to 
be JJSERENTRY.) The size of its stack in bytes is stack_size; the stack is 
allocated by the operating system after the stack size is rounded up to the 
next multiple of 4096. The thread arglist can be NULL, but must be present. 
.The thread terminates by simply returning, or by calling _endthread. 

The function uses the security _attr pointer to access the 
SECURITY_ATTRIBUTES structure. The structure contains the security 
attributes for the thread. If security _attr is NULL, the thread is created with 
default security attributes. The thread handle is not inherited if security _attr 
is NULL. 

The function reads the create Jiags variable for flags that provide additional 
information about the thread creation. This variable can be zero, specifying 
that the thread will run immediately upon creation. The variable can also 
be CREATE_SUSPENDED, in which case the thread will not run until the 
ResumeThread function is called. ResumeThread is provided by the Win32 
API. See the Win32 description of ResumeThread for additional information. 

The function initializes the thread Jd variable with the thread identifier. 

JbeginthreadNT returns the handle of the new thread. In the event of an 
error, the function returns -1, and the global variable errno is set to one of 
the following values: 



See also 



EAGAIN 
EINVAL 



Too many threads 
Invalid request 



Jbeginthread, _endthread 
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biosequip 



biosequip 



bios.h 




Function 
Syntax 



Remarks 



Return value 



Checks equipment. 

int biosequip (void) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 











biosequip uses BIOS interrupt Oxll to return an integer describing the equip- 
ment connected to the system. 

The return value is interpreted as a collection of bit-sized fields. The IBM 
PC values follow: 





Bits 14-15 Number of parallel printers installed 






00 = printers 






01 = 1 printer 






10 = 2 printers 






11 = 3 printers 




Bit 13 


Serial printer attached 




Bit 12 


Game I/O attached 


DOS only sees two 


Bits 9-11 


Number of COM ports 


ports but can be 
pushed to see four; 




000 = ports 


the IBM PS/2 can see 




001 = 1 port 


up to eight. 




010 = 2 ports 

011 = 3 ports 

100 = 4 ports 

101 = 5 ports 

110 = 6 ports 

111 = 7 ports 



Bit 8 Direct memory access (DMA) 

= Machine has DMA 

1 = Machine does not have DMA; for example, PC Jr. 

Bits 6-7 Number of disk drives 

00 = 1 drive 

01 = 2 drives 

10 = 3 drives 

11 = 4 drives, only if bit is 1 
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biosequip 



Bits 4-5 Initial video mode 

00 = Unused 

01 = 40x25 BW with color card 
10 = 80x25 BW with color card 

" 11 = 80x25 BW with mono card 

Bits 2-3 Motherboard RAM size 

00 = 16K 

01 = 32K 

10 = 48K 

11 = 64K 

Bit 1 Floating-point coprocessor 

Bit Boot from disk 



bios_equiplist 



bios.h 



Function 
Syntax 



Remarks 
Return value 



Checks equipment. 

unsigned _bios_equiplist(void) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 











_bios_equiplist uses BIOS interrupt 0x11 to return an integer describing the 
equipment connected to the system. 

The return value is interpreted as a collection of bit-sized fields. The IBM 
PC values follow: 



Bits 14-15 



Bit 13 
Bit 12 

Bits 9-11 



Number of parallel printers installed 

00 = printers 

01 = 1 printer 

10 = 2 printers 

11 = 3 printers 

Serial printer attached 
Game I/O attached 

Number of COM ports 

000 = ports 

001 = 1 port 

010 = 2 ports 

011 = 3 ports 

100 = 4 ports 

101 = 5 ports 
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_bios_equiplist 



110 = 6 ports 

111 = 7 ports 

Bit 8 Direct memory access (DMA) 

= Machine has DMA 

1 = Machine does not have DMA; for example, PC Jr. 

Bits 6-7 Number of disk drives 

00 = 1 drive 

01 = 2 drives 
10 = 3 drives 

11=4 drives, only if bit is 1 




Bit 4-5 


Initial video mode 




00 = Unused 




01 = 40x25 BW with color card 




10 = 80x25 BW with color card 




11 = 80x25 BW with mono card 


Bits 2-3 


Motherboard RAM size 




00 = 16K 




01 = 32K 




10 = 48K 




11 = 64K 


Bit 1 


Floating-point coprocessor 


BitO 


Boot from disk 



bioskey 



bios.h 



Function 
Syntax 



Remarks 
Return value 



Keyboard interface, using BIOS services directly. 

int bioskey (int cmd) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 















bioskey performs various keyboard operations using BIOS interrupt 0x16. 
The parameter cmd determines the exact operation. 

The value returned by bioskey depends on the task it performs, determined 
by the value of cnid: 



If the lower 8 bits are nonzero, bioskey returns the ASCII character 

for the next keystroke waiting in the queue or the next key 
pressed at the keyboard. If the lower 8 bits are zero, the upper 8 
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bioskey 



bits are the extended keyboard codes defined in the IBM PC 
Technical Reference Manual. 

This tests whether a keystroke is available to be read. A return 
value of zero means no key is available. The return value is 
OxFFFFF (-1) if Ctrl-Brkhas been pressed. Otherwise, the value of 
the next keystroke is returned. The keystroke itself is kept to be 
returned by the next call to bioskey that has a cmd value of zero. 

Requests the current shift key status. The value is obtained by 
ORing the following values together: 



Bit 7 


0x80 


Insert on 


Bit 6 


0x40 


Caps on 


Bit 5 


0x20 


Num Lock on 


Bit 4 


0x10 


Scroll Lock on 


Bit 3 


0x08 


Alt pressed 


Bit 2 


0x04 


Cfr/pressed 


Bitl 


0x02 


<— Shift pressed 


BitO 


0x01 


— > Shift pressed 



biosmemory 



bios.h 



Function 
Syntax 



Remarks 



Return value 



Returns memory size. 

int biosmemory (void) ; 
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biosmemory returns the size of RAM memory using BIOS interrupt 0x12. 
This does not include display adapter memory, extended memory, or 
expanded memory. 

biosmemory returns the size of RAM memory in IK blocks. 



bios memsize 



bios.h 



Function 
Syntax 



Returns memory size. 

unsigned _bios_memsize(void) • 
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bios memsize 



Remarks 



Return value 
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■ 











_bios_memsize returns the size of RAM memory using BIOS interrupt 0x12. 
This does not include display adapter memory, extended memory, or 
expanded memory. 

_bios_memsize returns the size of RAM memory in IK blocks. 



biostime 



bios.h 



Function 
Syntax 



Remarks 



Return value 



Reads or sets the BIOS timer. 

long biostime(int and, long newtime); 
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biostime either reads or sets the BIOS timer. This is a timer counting ticks 
since midnight at a rate of roughly 18.2 ticks per second, biostime uses 
BIOS interrupt OxlA. 

If cmd equals 0, biostime returns the current value of the timer. If cmd 
, equals 1, the timer is set to the long value in newtime. 

When biostime reads the BIOS timer (cmd - 0), it returns the timer's current 
value. 



biosjimeofday 



bios.h 



Function 
Syntax 



Remarks 



Reads or sets the BIOS timer. 

unsigned _bios_timeofday(int cmd, long *timep) ; 
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■ 




■ 











_bios_timeofday either reads or sets the BIOS timer. This is a timer counting 
ticks since midnight at a rate of roughly 18.2 ticks per second. 
Jbiosjimeofday uses BIOS interrupt OxlA. 
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_bios_timeofday 



The cmd parameter can be either of the following values: 



Return value 



_TIME_GETCLOCK The function stores the current BIOS timer value into 
the location pointed to by timep. If the timer has not 
been read or written since midnight, the function 
returns 1. Otherwise, the function returns 0. 



TIME SETCLOCK 



The function sets the BIOS timer to the long value 
pointed to by timep. The function does not return a 
value. 



The _bios_timeofday returns the value in AX that was set by the BIOS timer 
call. 



bsearch 



stdlib.h 



Function 
Syntax 



Remarks 



Binary search of an array. 

void *bsearch (const void *key, const void *base, size_t nelem, size_t width, 
int (JJSERENTRY *fcmp) (const void *, const void *)); 
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bsearch searches a table (array) of nelem elements in memory, and returns 
the address of the first entry in the table that matches the search key. The 
array must be in order. If no match is found, bsearch returns 0. Note that 
because this is a binary search, the first matching entry is not necessarily 
the first entry in the table. 

The type size J is defined in stddef .h header file. 

■ nelem gives the number of elements in the table. 

■ width specifies the number of bytes in each table entry. 

The comparison routine fcmp must be used with the _USERENTRY calling 
convention. 

fcmp is called with two arguments: eleml and eleml. Each argument points 
to an item to be compared. The comparison function compares each of the 
pointed-to items (*eleml and *elem2), and returns an integer based on the 
results of the comparison. 
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bsearch 



Return value 
See also 



For bsearch, the fcmp return value is 

■ < if *eleml < *eleml 

■ == if *eleml == *elem2 

■ > if *eleml > *eleml 

bsearch returns the address of the first entry in the table that matches the 
search key. If no match is found, bsearch returns 0. 

Ifind, Isearch, qsort 




cabs, cabsl 



math.h 



Function 
Syntax 



Remarks 



cabs 
cabsl 



Calculates the absolute value of complex number. 

double cabs (struct complex z); 

long double cabsl (struct _complexl z); 
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■ 


■ 






■ 



cabs is a macro that calculates the absolute value of z, a complex number, z 
is a structure with type complex. The structure is defined in math.h as 



struct complex { 
double x, y; 
}; 



struct _complexl { 

long double x, y; 
}; 



where x is the real part, and y is the imaginary part. 

Calling cabs is equivalent to calling sort with the real and imaginary 
components of z, as shown here: 

sqrt(z.x *'z.x + z.y * z.y) 

cabsl is the long double version; it takes a structure with type _complexl as 
an argument, and returns a long double result. 

If you're using C++, you may also use the complex class defined in 
complex.h, and use the function abs to get the absolute value of a complex 
number. 
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cabs, cabsl 



Return value 



See also 



cabs (or cabsl) returns the absolute value of z, a double. On overflow, cabs (or 
cabsl) returns HUGE_VAL (or _LHUGE_VAL) and sets the global variable 
errno to 

ERANGE Result out of range 

Error handling for these functions can be modified through the functions 
jnatherr and jnatherrl. 

abs, complex, errno (global variable), fobs, labs, jnatherr 



calloc 



stdlib.h 



Function 
Syntax 



Remarks 



Memory models are 
available only for 16- 
bit applications. 



Return value 
See also 



Allocates main memory. 

void *calloc(size_t nitems, size_t size); 
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■ 


■ 
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calloc provides access to the C memory heap. The heap is available for 
dynamic allocation of variable-sized blocks of memory. Many data 
structures, such as trees and lists, naturally employ heap memory 
allocation. 

All the space between the end of the data segment and the top of the 
program stack is available for use in the small data models (small, and 
medium), except for a small margin immediately before the top of the 
stack. This margin allows room for the application to grow on the stack, 
and provides a small amount of room needed by the operating system. 

In the large data models (compact, large, and huge), all space beyond the 
program stack to the end of physical memory is available for the heap. 

calloc allocates a block of size nitems x size. The block is cleared to 0. If you 
want to allocate a block larger than 64K, you must use farcalloc. 

calloc returns a pointer to the newly allocated block. If not enough space 
exists for the new block or if nitems or size is 0, calloc returns NULL. 

farcalloc, free, malloc, realloc 



ceil, ceill 



math.h 



Function 



Rounds up. 



46 



Library Reference 



ceil, ceill 



Syntax 



ceil 
ceill 



Remarks 
Return value 
See also 



double ceil (double x) ; 

long double ceill (long double x) 
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■ 
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■ 




ceil finds the smallest integer not less than x. ceill is the long double version; 
it takes a long double argument and returns a long double result. 

These functions return the integer found as a double (ceil) or a long double 

{ceill). 

floor, fmod 



c exit 



process.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Performs _exit cleanup without terminating the program. 

void _c_exit (void) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 
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_c_exit performs the same cleanup as _exit, except that it does not terminate 
the calling process. 

None. 

abort, atexit, _cexit, exec. . ., _exit, exit, signal, spawn.. . 



cexit 



process.h 



Function 
Syntax 



Remarks 



Performs exit cleanup without terminating the program. 

void _cexit(void) ; 
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_cexit performs the same cleanup as exit, except that it does not close files or 
terminate the calling process. Buffered output (waiting to be output) is 
written, and any registered "exit functions" (posted with atexit) are called. 
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cexit 



Return value 
See also 



None. 

abort, atexit, _c_exit,exec. . ., _exit, exit, signal, spawn.. 



cgets 



conio.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Reads a string from the console. 

char *cgets(char *str) ; 
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cgets reads a string of characters from the console, storing the string (and 
the string length) in the location pointed to by str. 

cgets reads characters until it encounters a carriage-return/linefeed 
(CR/LF) combination, or until the maximum allowable number of char- 
acters have been read. If cgets reads a CR/LF combination, it replaces the 
combination with a \0 (null character) before storing the string. 

Before cgets is called, set str[0] to the maximum length of the string to be 
read. On return, str[l] is set to the number of characters actually read. The 
characters read start at str[2] and end with a null character. Thus, str must 
be at least str[0] plus 2 bytes long. 

This function should not be used in Win32s or Win32 GUI applications. 

On success, cgets returns a pointer to str[2]. 

cputs, fgets, getch, getche, gets 



chain intr 



dos.h 



Function 
Syntax 



Remarks 



Chains to another interrupt handler. 

void _chain_intr (void '(interrupt far *newhandler) 
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The _chain_intr function passes control from the currently executing 
interrupt handler to the new interrupt handler whose address is 
newhandler. The current register set is not passed to the new handler. 
Instead, the new handler receives the registers that were stacked (and 
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chain intr 



Return value 
See also 



possibly modified in the stack) by the old handler. The new handler can 
simply return, as if it were the original handler. The old handler is not 
entered again. 

The _chain_intr function can be called only by C interrupt functions. It is 
useful when writing a TSR that needs to insert itself in a chain of interrupt 
handlers (such as the keyboard interrupt). 

None. 

_dos_getvect, _dos_setvect, 




chdir 



dir.h 



Function 
Syntax 



Remarks 



Return value 



Changes current directory. 

int chdir (const char *path) ; 
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■ 



chdir causes the directory specified by path to become the current working 
directory, path must specify an existing directory. 

A drive can also be specified in the path argument, such as 

chdir("a:\\BC") 

but this changes only the current directory on that drive; it doesn't change 
the active drive. 

Only the current process is affected. 

Upon successful completion, chdir returns a value of 0. Otherwise, it returns 
a value of -1, and the global variable errno is set to 



See also 



ENOENT Path or file name not found 
getcurdir, getcwd, getdisk, mkdir, rmdir, setdisk, system 



chdrive 



direct.h 



Function 
Syntax 



Sets current disk drive. 

int _chdrive(int drive); 
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chdrive 



Remarks 

Return value 
See also 
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_chdrive sets the current drive to the one associated with drive: 1 for A, 
2 for B, 3 for C, and so on. 

This function changes the current drive of the parent process. 

jchdrive returns if the current drive was changed successfully; otherwise, 
it returns -1. 

dos setdrive 



chmod 



dos.h, io.h 



Obsolete function. See rtl chmod. 



chmod 



sys\stat.h 



Function 
Syntax 



Remarks 



Changes file access mode. 

int chmod(const char *path, int amode); 
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chmod sets the file-access permissions of the file given by path according to 
the mask given by amode. path points to a string. 

amode can contain one or both of the symbolic constants S_IWRITE and 
SJREAD (defined in sys\stat.h). 



Return value 



Value of amode 



Access permission 



SJWRITE 

SJREAD 

S IREADIS IWRITE 



Permission to write 
Permission to read 
Permission to read and write 



Write permission implies read permission. 

Upon successfully changing the file access mode, chmod returns 0. Other- 
wise, chmod returns a value of -1. 
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chmod 



See also 



In the event of an error, the global variable errno is set to one of the 
following values: 

EACCES Permission denied 
ENOENT Path or file name not found 

access, _rtl_chmod, fstat, open, sopen, stat 




chsize 



io.h 



Function 
Syntax 



Remarks 



Return value 



Changes the file size. 

int chsizefint handle, long size); 
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chsize changes the size of the file associated with handle. It can truncate or 
extend the file, depending on the value of size compared to the file's original 
size. 

The mode in which you open the file must allow writing. 

If chsize extends the file, it will append null characters (\0). If it truncates 
the file, all data beyond the new end-of-file indicator is lost. 

On success, chsize returns 0. On failure, it returns -1 and the global variable 
errno is set to one of the following values: 



See also 



EACCES Permission denied 
EBADF Bad hie number 

ENOSPC No space left on device 

close, _rtl_creat, creat, open 



clear87 



float.h 



Function 
Syntax 



Clears floating-point status word. 

unsigned int _clear87 (void) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 
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clear87 



Remarks 



Return value 



See also 



_clear87 clears the floating-point status word, which is a combination of the 
80x87 status word and other conditions detected by the 80x87 exception 
handler. 

The bits in the value returned indicate the floating-point status before it 
was cleared. For information on the status word, refer to the constants 
defined in float.h. 

_control87, _fpreset, _status87 



clearerr 



stdio.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Resets error indication. 

void clearerr (FILE *stream) ; 
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clearerr resets the named stream's error and end-of-file indicators to 0. Once 
the error indicator is set, stream operations continue to return error status 
until a call is made to clearerr or rewind. The end-of-file indicator is reset 
with each input operation. 

None. 

eof, feof, f error, perror, rewind 



clock 



time.h 



Function 
Syntax 



Remarks 



Return value 



Determines processor time. 

,clock_t clock (void); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 


■ 


■ 
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clock can be used to determine the time interval between two events. To 
determine the time in seconds, the value returned by clock should be 
divided by the value of the macro CLK_TCK. 

The clock function returns the processor time elapsed since the beginning of 
the program invocation. If the processor time is not available, or its value 
cannot be represented, the function returns the value -1. 



52 



Library Reference 



See also 

close 



clock 



time 




Obsolete function. See rtl close. 



close 



io.h 



Function 
Syntax 



Remarks 



Return value 



See also 

closedir 

Function 
Syntax 



Remarks 



Closes a file. 

int close(int handle); 
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■ 



close closes the file associated with handle, a file handle obtained from a 
_rtl_creat, creat, creatnew, creattemp, dup, dup2, _rtl_open, or open call. 

The function does not write a Ctrl-Z character at the end of the file. If you 
want to terminate the file with a Ctrl-Z, you must explicitly output one. 

Upon successful completion, close returns 0. Otherwise, the function returns 
a value of-1. 

close fais if handle is not the handle of a valid, open file, and the global 
variable errno is set to 

EBADF Bad file number 
chsize, creat, creatnew, dup, fclose, open, _rtl_close, sopen 

dirent.h 

Closes a directory stream. 

int closedir (DIR *dirp) ; 
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On UNIX platforms, closedir is available on POSIX-compliant systems. 
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closedir 



Return value 



See also 



The closedir function closes the directory stream dirp, which must have been 
opened by a previous call to opendir. After the stream is closed, dirp no 
longer points to a valid directory stream. 

If closedir is successful, it returns 0. Otherwise, closedir returns -1 and sets 
the global variable errno to 

EBADF The dirp argument does not point to a valid open directory 

stream 

errno (global variable), opendir, readdir, rewinddir 



clreol 



conio.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Clears to end of line in text window. 

void clreol (void) ; 
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clreol clears all characters from the cursor position to the end of the line 
within the current text window, without moving the cursor. 

This function should not be used in Win32s or Win32 GUI applications. 

None. 

clrscr, delline, window 



clrscr 



conio.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Clears the text-mode window. 

void clrscr (void) ; 
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clrscr clears the current text window and places the cursor in the upper 
left-hand corner (at position 1,1). 

This function should not be used in Win32s or Win32 GUI applications. 

None. 

clreol, delline, window 
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control87 



_control87 

Function 
Syntax 



Remarks 



float.h 



Manipulates the floating-point control word. 

unsigned int _contro!87 (unsigned int newcw, unsigned int mask) 
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_control87 retrieves or changes the floating-point control word. 

The floating-point control word is an unsigned int that, bit by bit, specifies 
certain modes in the floating-point package; namely, the precision, infinity, 
and rounding modes. Changing these modes lets you mask or unmask 
floating-point exceptions. 

_control87 matches the bits in mask to the bits in newcw. If a mask bit equals 
1, the corresponding bit in newcw contains the new value for the same bit in 
the floating-point control word, and _control87 sets that bit in the control 
word to the new value. 

Here's a simple illustration: 



Return value 



See also 



Original control word: 


0100 


0011 


0110 


0011 


mask: 


1000 


0001 


0100 


1111 


newcw: 


1110 


1001 


0000 


0101 


Changing bits: 


lxxx 


xxxl 


xOxx 


0101 



If mask equals 0, _control87 returns the floating-point control word without 
altering it. - 

The bits in the value returned reflect the new floating-point control word. 
For a complete definition of the bits returned by _control87, see the header 
file float.h. 

_clear87, Jpreset, signal, _status 87 



cos, cosl 



math.h 



Function 



Calculates the cosine of a value. 
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cos, cosl 



Syntax 



Remarks 



cos 



cosl 



Return value 



See also 



double cos (double x) ; 

long double cosl (long double x) ; 
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cos computes the cosine of the input value. The angle is specified in radians. 

cosl is the long double version; it takes a long double argument and returns 
a long double result. 

This function can be used with bed and complex types. 

cos of a real argument returns a value in the range -1 to 1. Error handling 
for these functions can be modified through jnatherr (or jnatherrl). 

acos, asin, atari, atan2, bed, complex, jnatherr, sin, tan 



cosh, coshl 



math.h 



Function 



Syntax 



cosh 
coshl 



Remarks 



Return value 



Calculates the hyperbolic cosine of a value. 

double cosh (double x) ; 

long double coshl (long double x) ; 
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See also 



cosh computes the hyperbolic cosine, (e x + e" x )/2. coshl is the long double 
version; it takes a long double argument and returns a long double result. 

This function can be used with bed and complex types. 

cosh returns the hyperbolic cosine of the argument. 

When the correct value would create an overflow, these functions return 
the value HUGE_VAL (cosh) or _LHUGE_VAL (coshl) with the appropriate 
sign, and the global variable errno is set to ERANGE. Error handling for 
these functions can be modified through the functions jnatherr and 
jnatherrl. 

acos, asin, atan, atanl, bed, complex, cos, jnatherr, sin, sinh, tan, tanh 
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country 



country 



dos.h 




Function 
Syntax 



Remarks 



The country function 

is not affected by 

setlocale. 



Returns country-dependent information. 

struct COUNTRY *country(int xcode, struct COUNTRY *cp) ; 
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country specifies how certain country-dependent data (such as dates, times, 
and currency) will be formatted. The values set by this function depend on 
the operating system version being used. 

If cp has a value of -1, the current country is set to the value of xcode, which 
must be nonzero. The COUNTRY structure pointed to by cp is filled with' 
the country-dependent information of the current country (if xcode is set to 
zero), or the country given by xcode. 

The structure COUNTRY is defined as follows: 



struct COUNTRY { 






int co_date; 


/* 


date format */ 


char co_curr[5] ; 


/* 


currency symbol */ 


char co_thsep[2] 


/* 


thousands separator */ 


char co_desep[2] 


/* 


decimal separator */ 


char co_dtsep[2] 


. /* 


date separator */ 


char co_tmsep[2] 


/* 


time separator */ 


char co_currstyl( 


2; /* 


currency style */ 


v - char co_digits; 


/* 


significant digits in currency */ 


char co_time; 


/* 


time format */ 


long co_case; 


/* 


case map */ 


char co_dasep[2] 


/* 


data separator */ 


char co_fill[10] 


7* 


filler */ 



}; 



The date format in co date is 



1 for the U.S. style of month, day, year. 

1 1 for the European style of day, month, year. 

1 2 for the Japanese style of year, month, day. 
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country 



Return value 



Currency display style is given by co_currstyle as follows: 

■ for the currency symbol to precede the value with no spaces between 
the symbol and the number. 

■ 1 for the currency symbol to follow the value with no spaces between the 
number and the symbol. 

■ 2 for the currency symbol to precede the value with a space after the 
symbol. 

■ 3 for the currency symbol to follow the number, with a space before the 
symbol. 

On success, country returns the pointer argument cp. On error, it returns 
NULL. 



cprintf 



conio.h 



Function 
Syntax 



Remarks 



Writes formatted output to the screen. 

int cprintf (const char *format[, argument, ...]); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 






■ 






■ 



cprintf accepts a series of arguments, applies to each a format specifier 
contained in the format string pointed to by format, and outputs the 
See printf lor details formatted data directly to the current text window on the screen. There 
on format specifiers. mus t be the same number of format specifiers as arguments. 

The string is written either directly to screen memory or by way of a BIOS 
call, depending on the value of the global variable directvideo. 

Unlike fprintf and printf, cprintf does not translate linefeed characters (\n) 
into carriage-return/linefeed character pairs (\r\n). Tab characters 
(specified by \t) are not expanded into spaces. 



Return value 
See also 



This function should not be used in Win32s or Win32 GUI applications. 

cprintf returns the number of characters output. 

directvideo (global variable), fprintf, printf, putch, sprintf, vprintf 
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cputs 



cputs 



conio.h 




Function 
Syntax 



Remarks 



Return value 
See also 



Writes a string to the screen. 

int cputs (const char *str) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 






■ 






■ 



cputs writes the null-terminated string str to the current text window. It 
does not append a newline character. 

The string is written either directly to screen memory or by way of a BIOS 
call, depending on the value of the global variable directvideo. Unlike puts, 
cputs does not translate linefeed characters (\n) into carriage- 
return/linefeed character pairs (\r\n). 

This function should not be used in Win32s or Win32 GUI applications. 

cputs returns the last character printed. 

cgets, _directvideo (global variable), fputs,pu tch, puts 



creat 



io.h 



Obsolete function. See rtl creat. 



creat 



io.h 



Function 
Syntax 



Remarks 



Creates a new file or overwrites an existing one. 

.int creat (const char *path, int amode) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++' 


OS/ 


■ 


■ 


" 


■ 






■ 



creat creates a new file or prepares to rewrite an existing file given by path, 
amode applies only to newly created files. 

A file created with creat is always created in the translation mode specified 
by the global variable Jmode (0_TEXT or 0_BINARY). 
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creat 



If the file exists and the write attribute is set, creat truncates the file to a 
length of bytes, leaving the file attributes unchanged. If the existing file 
has the read-only attribute set, the creat call fails and the file remains 
unchanged. 

The creat call examines only the S_IWRITE bit of the access-mode word 
amode. If that bit is 1, the file can be written to. If the bit is 0, the file is 
marked as read-only. All other operating system attributes are set to 0. 

amode can be one of the following (defined in sys\stat.h): 



Return value 



Value of amode 



SJWRITE , 

SJREAD 

S IREADIS IWRITE 



Access permission 



Permission to write 
Permission to read 
Permission to'read and write 



Write permission implies read permission. 

Upon successful completion, creat returns the new file handle, a non- 
negative integer; otherwise, it returns -1. 

In the event of error, the global variable errno is set to one of the following: 



See also 



EACCES Permission denied 
EMFILE Too many open files 
ENOENT Path or file name not found 

chtnod, chsize, close, _rtl_creat, creatnew, creattemp, dup, dup2, Jmode (global 
variable), fopen, open, sopen, write 



creatnew 



io.h 



Function 
Syntax 



Remarks 



Creates a new file. 

int creatnew (const char *path, int mode); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 






■ 



creatnew is identical to _rtl_creat with one exception: If the file exists, 
creatnew returns an error and leaves the file untouched. 
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creatnew 



Return value 



See also 



The mode argument to creatnew can be zero or an OR-combination of any 
one of the following constants (defined in dos.h): 

FA_HIDDEN Hidden file 
FA_RDONLY Read-only attribute 
FA_SYSTEM System file 

Upon successful completion, creat returns the new file handle, a non- 
negative integer; otherwise, it returns -1. 

In the event of error, the global variable errno is set to one of the following 
values: 

EACCES Permission denied 

EEXIST File already exists 

EMFILE Too many open files 

ENOENT Path or file name not found 

close, _rtl_creat, creat, creattemp, _dos_creatnezv, dup, Jmode (global variable), 
open 




creattemp 



io.h 



Function 
Syntax 



Remarks 



Remember that a 

backslash in path 

requires 'W. 



Creates a unique file in the directory associated with the path name. 

int creattemp (char *path, int attrib) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 






■ 



A file created with creattemp is always created in the translation mode 
specified by the global variable Jmode (0_TEXT or 0_BINARY). 

path is a path name ending with a backslash (\). A unique file name is 
selected in the directory given by path. The newly created file name is 
stored in the path string supplied, path should be long enough to hold the 
resulting file name. The file is not automatically deleted when the program 
terminates. 

creattemp accepts attrib, a DOS attribute word. Upon successful file 
creation, the file pointer is set to the beginning of the file. The file is opened 
for both reading and writing. 
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creattemp 



Return value 



The attrib argument to creattemp can be zero or an OR-combination of any- 
one of the following constants (defined in dos.h): 

FA_HIDDEN Hidden file 
FA_RDONLY Read-only attribute 
FA_SYSTEM System file 

Upon successful completion/the new file handle, a nonnegative integer, is 
returned; otherwise, -1 is returned. 

In the event of error, the global variable errno is set to one of the following 
values: 



See also 



EACCES Permission denied 

EMFILE Too many open files 

ENOENT Path or file name not found 

close, _rtl_creat, creat, creatnew, dup, Jmode (global variable), open 



_crotl, _crotr 



stdlib.h 



Function 
Syntax 



Remarks 



Return value 



See also 



Rotates an unsigned char left or right. 

unsigned char _crotl (unsigned char val, int count); 
unsigned char _crotr (unsigned char val, int count); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 






■ 



_crotl rotates the given val to the left count bits. _crotr rotates the given val to 
the right count bits. 

The argument val is an unsigned char, or its equivalent in decimal or hexa- 
decimal form. 

The functions return the rotated val. 

■ _crotl returns the value of val left-rotated count bits. 

■ jorotr returns the value of val right-rotated count bits. 

Jrotl, Jrotr, jrotl, jotr 
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cscanf 



conio.h 




Function 
Syntax 



Remarks 



See scanf for details 
on format specifiers. 



Return value 



See also 



Scans and formats input from the console. 

int cscanf (char *format[, address, ...]); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 






■ 






. ■ 



cscanf scans a series of input fields one character at a time, reading directly 
from the console. Then each field is formatted according to a format 
specifier passed to cscanf in the format string pointed to by format. Finally, 
cscanf stores, the formatted input at an address passed to it as an argument 
following format, and echoes the input directly to the screen. There must be 
the same number of format specifiers and addresses as there are input 
fields. 

cscanf might stop scanning a particular field before it reaches the normal 
end-of-field (whitespace) character, or it might terminate entirely for a 
number of reasons. See scanf for a discussion of possible causes. 

This function should not be used in Win32s or Win32 GUI applications. 

cscanf returns the number of input fields successfully scanned, converted, 
and stored; the return value does not include scanned fields that were not 
stored. If no fields were stored, the return value is 0. 

If cscanf attempts to read at end-of-file , the return value is EOF. 

fscanf, getche, scanf, sscanf 



ctime 



time.h 



Function 
Syntax 



Converts date and time to a string. 

char *ctime( const time_t *time) ; 



DOS 


UNIX . 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 
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ctime 



Remarks 



Return value 



See also 



ctime converts a time value pointed to by time (the value returned by the 
function time) into a 26-character string in the following form, terminating 
with a newline character and a null character: 

Mon Nov 21 11:31:54 1983\n\0 

All the fields have constant width. 

The global long variable timezone contains the difference in seconds 
between GMT and local standard time (in PST, timezone is 8x60x60). The. 
global variable daylight is nonzero if and only if the standard U.S. daylight 
saving time conversion should be applied. These variables are set by the 
tzset function, not by the user program directly. 

ctime returns a pointer to the character string containing the date and time. 
The return value points to static data that is overwritten with each call to 
ctime. 

asctime, _daylight (global variable), difftime, ftime, getdate, gmtime, localtime, 
settime, time, Jimezone (global variable), tzset 



ctrlbrk 



dos.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Sets control-break handler. 

void ctrlbrk(int (*handler) (void) ) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 











ctrlbrk sets a new control-break handler function pointed to by handler. The 
interrupt vector 0x23 is modified to call the named function. 

ctrlbyk establishes a DOS interrupt handler that calls the named function; 
the named function is not called directly. 

The handler function can perform any number of operations and system 
calls. The handler does not have to return; it can use longjmp to return to an 
arbitrary point in the program. The handler function returns to abort the 
current program; any other value causes the. program to resume execution. 

ctrlbrk returns nothing. 

getcbrk, signal 
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cwait 



cwait 



process.h 




Function 
Syntax 



Remarks 



Waits for child process to terminate. 

int cwait (int *statloc, int pid, int action); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 








■ 






■ 



The cwait function waits for a child process to terminate. The process ID of 
the child to wait for is pid. If statloc is not NULL, it points to the location 
where cwait will store the termination status. The action specifies whether to 
wait for the process alone, or for the process and all of its children. 

If the child process terminated normally (by calling exit, or returning from 
main), the termination status word is defined as follows: 



Bits 0-7 Zero. 

Bits 8-1 5 The least significant byte of the return code from the child 

process. This is the value that is passed to exit, or is returned 
from main. If the child process simply exited from main with- 
out returning a value, this value will be unpredictable. 

If the child process terminated abnormally, the termination status word is 
defined as follows: 

Bits 0-7 Termination information about the child: 



. 1 
2 
3 

Bits 8-15 Zero. 



Critical error abort. 

Execution fault, protection exception. 

External termination signal. 



If pid is 0, cwait waits for any child process to terminate. Otherwise, pid 
specifies the process ID of the process to wait for; this value must have been 
obtained by an earlier call to an asynchronous spawn function. 

The acceptable values for action are WAIT_CHILD, which waits for the 
specified child only, and WAIT_GRANDCHILD, which waits for the 
specified child and all of its children. These two values are defined in 
process.h. 
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cwait 



Return value 



See also 



When cwait returns after a normal child process termination, it returns the 
process ID of the child. 

When cwait returns after an abnormal child termination, it returns -1 to the 
parent and sets errno to EINTR (the child process terminated abnormally). 

If cwait returns without a child process completion, it returns a -1 value 
and sets errno to one of the following values: 



ECHILD 
EINVAL 

spawn, wait 



No child exists or the pid value is bad 
A bad action value was specified 



delline 



conio.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Deletes line in text window. 

void delline (void); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 






■ 



delline deletes the line containing the cursor and moves all lines below it 
one line up. delline operates within the currently active text window. 

This function should not be used in Win32s or Win32 GUI applications. 

None. 

clreol, clrscr, insline, window 



difftime 



time.h 



Function 
Syntax 



Remarks 



Computes the difference between two times. 

double difftime (time_t time2, time_t timel); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


• ■ 



difftime calculates the elapsed time in seconds, from timel to timel. 
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difftime 



Return value 
See also 



difftime returns the result of its calculation as a double. 

asctime, dime, _daylight (global variable), gtntime, localtime, time, Jimezone 
(global variable) 



disable, disable, enable, enable 



dos.h 




Function 
Syntax 



Remarks 



Return value 
See also 



Disables and enables interrupts. 

void disable (void) ; 
void _disable(void) ; 
void enable (void) ; 
void _enable (void) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




" 


■ 









These macros are designed to provide a programmer with flexible 
hardware interrupt control. 

The disable and _disable macros disable interrupts. Only the NMI (non- 
maskable interrupt) is allowed from any external device. 

The enable and _enable macros enable interrupts, allowing any device 
interrupts to occur. 

None. 

getvect 



div 



stdlib.h 



Function 
Syntax 



Remarks 



Divides two integers, returning quotient and remainder. 

div_t div(int numer, int denom) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 


■ 


■ 


■ 



div divides two integers and returns both the quotient and the remainder as 
a div J type, numer and denom are the numerator and denominator, 
respectively. The div_t type is a structure of integers defined (with typedef) 
in stdlib.h as follows: 
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div 



typedef struct { 
int quot ; 
int rem; 

} div_t; 



/* quotient */ 
/* remainder */ 



Return value div returns a structure whose elements are quot (the quotient) and rem (the 

remainder). 

See also ui v 



dos close 



dos.h 



Function 
Syntax 



Remarks 
Return value 

See also 



Closes a file. 

unsigned _dos_close(int handle); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


v 


■ 








■ 



_dos_close closes the file associated with handle, handle is a file handle 
obtained from a _dos_creat, _dos_creatnew, or _dos_open call. 

Upon successful completion, _dos_close returns 0. Otherwise, it returns the 
operating system error code and the global variable errno is set to 

EBADF Bad file number 

_dos_creat, _dos_open, _dos_read, _dos_write 



dos commit 



dos.h 



Function 
Syntax 



Remarks 
Return value 
See also 



Output a file to the disk. 

unsigned _dos_commit (int handle); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 











This function makes DOS flush any output that it has buffered for a specific 
handle to the disk. 

The function returns zero on success. On failure the function returns the 
DOS error code and sets errno to EBADF. 

_rtl_close, _rtl_creat, _dos_creat, _dos_write ' 
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dos creat 



_dos_creat 

Function 
Syntax 



Remarks 



dos.h, io.h 



Creates a new file or overwrites an existing one. 

unsigned _dos_creat (const char *path,int attrib.int *handlep) 




DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 








■ 



_dos_creat opens the file specified by path. The file is always opened in 
binary mode. Upon successful file creation, the file pointer is set to the 
beginning of the file. _dos_creat stores the file handle in the location pointed 
to by handlep. The file is opened for both reading and writing. 

If the file already exists, its size is reset to 0. (This is essentially the same as 
deleting the file and creating a new file with the same name.) 



Return value 



See also 



FA_RDONLY Read-only attribute 
FA_HIDDEN Hidden file 
FA_SYSTEM System file 

The attrib argument is an ORed combination of one or more of the 
following constants (defined in dos.h): 

_A_NORMAL Normal file 

_A_RDONLY Read-only file 

_A_HIDDEN Hidden file 

_A_SYSTEM System file 

Upon successful completion, _dos_creat returns 0. If an error occurs, 
_dos_creat returns the operating system error code. 

In the event of error, the global variable errno is set to one of the following 
values: 

EACCES Permission denied 
EMFILE Too many open files 
ENOENT Path or file name not found 

chsize, close, creat, creatnew, creattemp, _rtl_chmod, _rtl_close 



dos creatnew 



dos.h 



Function 



Creates a new file. 
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dos creatnew 



Syntax 



unsigned _dos_creatnew( const char *path, int attrib, int *handlep) 



Remarks 



Return value 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 








■ 



See also 



_dos_creatnew creates and opens the new file path. The file is given the 
access permission attrib, an operating-system attribute word. The file is 
always opened in binary mode. Upon successful file creation, the file 
handle is stored in the location pointed to by handlep, and the file pointer is 
set to the beginning of the file. The file is opened for both reading and 
writing. 

If the file already exists, _dos_creatnew returns an error and leaves the file 
untouched. 

The attrib argument to _dos_creatnew is an OR combination of one or more 
of the following constants (defined in dos.h): 

_A_NORMAL Normal file 

_A_RDONLY Read-only file 

_A_HIDDEN Hidden file 

_A_SYSTEM System file 

Upon successful completion, _dos_creatnew returns 0. Otherwise, it returns 
the operating system error code, and the global variable errno is set to one 
of the following: 

EACCES Permission denied 

EEXIST File already exists 

EMFILE Too many open files 

ENOENT Path or file name not found 

creatnew, _dos_close, _dos_creat, _dos_getfileattr, _dos_setfileattr 



dosexterr 



dos.h 



Function 
Syntax 



Gets extended DOS error information. 

int dosexterr (struct D0SERR0R *eblkp) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 
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dosexterr 



Remarks 



Return value 



This function fills in the DOSERROR structure pointed to by eblkp with 
extended error information after a DOS call has failed. The structure is 
defined as follows: 



struct DOSERROR { 

int de_exterror; 

char de_class; 

char de_action; 

char de_locus; 
}; 



/* extended error */ 

/* error class */ 

/* action */ 

/* error locus */ 




The values in this structure are obtained by way of DOS call 0x59. A 
de_exterror value of indicates that the prior DOS call did not result in an 
error. 

dosexterr returns the value de exterror. 



dos findfirst 



dos.h 



Function 
Syntax 



Remarks 



Searches a disk directory. 

unsigned _dos_findfirst (const char *pathname,,,int attrib, 
struct find_t *f fblk) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 








■ 



_dos_findfirst begins a search of a disk directory. 

pathname is a string with an optional drive specifier, path, and file name of 
the file to be found. The file name portion can contain wildcard match 
characters (such as ? or *). If a matching file is found, the findjt structure 
pointed to by ffblk is filled with the file-directory information. 

The format of the findjt structure is as follows: 



struct find_t { 




char reserved [21] ; 


/* reserved by the operating system */ 


char attrib; 


/* attribute found */ 


int wr_time; 


/* file time */ 


int wr_date; 


' /* file date */ 


long size; 


/* file size */ 


char name [13] ; 


/* found file name */ 



. }; . 

attrib is an operating system file-attribute word used in selecting eligible 
files for the search, attrib is an OR combination of one or more of the 
following constants (defined in dos.h): 
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dos findfirst 



A_NORMAL 
_A_RDONLY 
A_HIDDEN 
A_SYSTEM 
A_VOLID 
A_SUBDIR 
A ARCH 



Normal file 
Read-only attribute 
Hidden file 
System file 
Volume label 
Directory 
Archive 



For more detailed information about these attributes, refer to your 
operating system reference manuals. 

Note that wrjtime and wr_date contain bit fields for referring to the file's 
date and time. The structure of these fields was established by the operat- 
ing system. 



Return value 



See also 



wr_time: 

Bits 0-4 

Bits 5-10 
Bits 11-15 



wr_date: 

Bits 0-4 
Bits 5-8 
Bits 9-15 



The result of seconds divided by 2 (for example, 10 

here means 20 seconds) 

Minutes 

Hours 



Day 

Month 

Years since 1980 (for example, 9 here means 1989) 

_dos_findfirst returns on successfully finding a file matching the search 
pathname. When no more files can be found, or if there is some error in the 
file name, the operating system error code is returned, and the global 
variable errno is set to 

ENOENT Path or file name not found 

_dos_findnext 



dos findnext 



dos.h 



Function 
Syntax 



Remarks 



Continues _dos_findfirst search. 

unsigned _dos_f indnext ( struct find_t *ffblk); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


, ■ 




■ 








■ 



_dos_findnext is used to fetch subsequent files that match the pathname given 
in _dos_Jindfirst. ffblk is the same block filled in by the _dos_findfirst call. This 
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dos findnext 



Return value 



See also 



block contains necessary information for continuing the search. One file 
name for each call to _dos_findnext is returned until no more files are found 
in the directory matching the pathname. 

_dos_findnext returns on successfully finding a file matching the search 
pathname. When no more files can be found, or if there is some error in the 
file name, the operating system error code is returned, and the global 
variable errno is set to 



ENOENT 
_dos_findfirst 



Path or file name not found 




dos_getdate, _dos_setdate, getdate, setdate 



dos.h 



Function 
Syntax 



Remarks 



Gets and sets system date. 

void _dos_getdate( struct dosdate_t *datep) ; 
unsigned _dos_setdate( struct dosdate_t *datep); 
void getdate (struct date *datep) ; 
void setdate (struct date *datep) ; 



DOS 
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Win 32 
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ANSI C++ 
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■ 




■ 








■ 



getdate fills in the date structure (pointed to by datep) with the system's 
current date. 

setdate sets the system date (month, day, and year) to that in the date 
structure pointed to by datep. 

The date structure is defined as follows: 



struct date { 
int da_year; 
char da_day; 
char da_mon; 

}; 



/* current year */ 
/* day of the month */ 
/* month (1 = Jan) */ 



_dos_getdate fills in the dosdatejt structure (pointed to by datep) with the 
system's current date. 
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_dos_getdate, _dos_setdate, getdate, setdate 



The dosdate t structure is defined as follows: 



Return value 



See also 



struct dosdate_t { 




unsigned char day; 


/* 1-31 */ 


unsigned char month; 


/* 1-12 */ 


unsigned int year; 


/* 1980 - 2099 */ 


unsigned char day of week; 
}; 


/* - 6 (0=Sunday) 



_dos_getdate, getdate, and setdate do not return a value. 

If the date is set successfully, _dos_setdate returns 0. Otherwise, it returns a 
nonzero value and the global variable errno is set to 

EINVAL Invalid date 

ctime, gettime, settime 



dos_getdiskfree 



dos.h 



Function 
Syntax 



Remarks 



Return value 



See also 



Gets disk free space. 

unsigned _dos_getdiskfree (unsigned char drive, struct diskfree_t *dtable) 
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■ 








■ 



_dos_getdiskfree accepts a drive specifier in drive (0 for default, 1 for A, 2 for 
B, and so on) and fills in the diskfreej structure pointed to by dtable with 
disk characteristics. 

The diskfreejt structure is defined as follows: 



struct diskfree_t { 

unsigned avail_clusters; 

unsigned total_clusters; 

unsigned bytes_per_sector; 

unsigned sectors_per_cluster; 
}; 



/* available clusters */ 

/* total clusters */ 

/* bytes per sector */ 

/* sectors per cluster */ 



_dos_getdiskfree returns if successful. Otherwise, it returns a nonzero value 
and the global variable errno is set to 



EINVAL 
getfat, getfatd 



Invalid drive specified 
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_dos_getdrive, _dos_setdrive 



_dos_getdrive, _dos_setdrive 



dos.h 




Function 
Syntax 



Remarks 



Return value 
See also 



Gets and sets the current drive number. 

void _dos_getdrive (unsigned *drivep) ; 

void _dos_setdrive (unsigned drivep, unsigned *ndrives); 
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UNIX 
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■ 








■ 



_dos_getdrive gets the current drive number. 

_dos_setdrive sets the current drive and stores the total number of drives at 
the location pointed to by ndrives. 

The drive numbers at the location pointed to by drivep are as follows: 1 for 
A, 2 for B, 3 for C, and so on. 

This function changes the current drive of the parent process. 

None. Use _dos_getdrive to verify that the current drive was changed 
successfully. 

getczvd 



dos_getfileattr,_dos_setfileattr 



dos.h 



Function 
Syntax 



Remarks 



Changes file access mode. 

int _dos_getfileattr (const char *path, unsigned *attribp) ; 
int _dos_setfileattr (const char *path, unsigned attrib) ; 
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■ 








■ 



_dos_getfileattr fetches the file attributes for the file path. The attributes are 
stored at the location pointed to by attribp. 

_dos_setfileattr sets the file attributes for the file path to the value attrib. The 
file attributes can be an OR combination of the following symbolic 
constants (defined in dos.h): 



A_RDONLY 
A HIDDEN 



Read-only attribute 
Hidden file 
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_dos_getfileattr,_dos_setfileattr 



Return value 



See also 



_A_SYSTEM System file 

_A_VOLID Volume label 

_A_SUBDIR Directory 

_A_ARCH Archive 

_A_NORMAL Normal file (no attribute bits set) 

Upon successful completion, _dos_getfileattr and _dos_setfileattr return 0. 
Otherwise, these functions return the operating system error code, and the 
global variable errno is set to 

ENOENT Path or file name not found 

chmod, stat 



_dos_getftime, _dos_setftime 



dos.h 



Function 
Syntax 



Remarks 



Gets and sets file date and time. 

unsigned _dos_getftime(int handle, unsigned *datep, unsigned *timep) 
unsigned _dos_setftime(int handle, unsigned date, unsigned time); 
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■ 








■ 



_dos_getftime retrieves the file time and date for the disk file associated with 
the open handle. The file must have been previously opened using 
_dos_open, _dos_creat, or _dos_creatnew. _dos_getftime stores the date and 
time at the locations pointed to by datep and timep. 

_dos_setftime sets the file's new date and time values as specified by date and 
time. 

Note that the date and time values contain bit fields for referring to the file's 
date and time. The structure of these fields was established by the operat- 
ing system. 



Date: 




Bits 0-4 


Day 


Bits 5-8 


Month 


Bits 9-15 


Years since 1980 (for example, 9 here means 1989) 


Time: 




Bits 0-4 


The result of seconds divided by 2 (for example, 10 here 




means 20 seconds) 


Bits 5-10 


Minutes 


Bits 11-15 


Hours 
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_dos_getftime, _dos_setftime 



Return value 



See also 



_dos_getftime and _dos_setftime return on success. 

In the event of an error return, the operating system error code is returned 
and the global variable errno is set to one of the following values: 



EACCES 
EBADF 

fstat, stat 



Permission denied 
Bad file number 




dos_gettime, _dos_settime 



dos.h 



Function 
Syntax 



Remarks 



Return value 



See also 



Gets and sets system time. 

void _dos_gettime( struct dostime_t *timep) ; 
unsigned _dos_settime( struct dostimej: *timep) ; 
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ANSI C++ 
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■ 



_dos_gettime fills in the dostimej structure pointed to by timep with the sys- 
tem's current time. 

_dos_settime sets the system time to the values in the dostimejt structure 
pointed to by timep. 

The dostime t structure is defined as follows: 



struct dostimej: { 

unsigned char hour; 

unsigned char minute; 

unsigned char second; 

unsigned char hsecond; 
}; 



/* hours 0-23 */ 

/* minutes 0-59 */ 

/* seconds 0-59 */ 

/* hundredths of seconds 



-99 */ 



_dos_gettime does not return a value. 

If _dos_settime is successful, it returns 0. Otherwise, it returns the operating 
system error code, and the global variable errno is set to: 

EINVAL Invalid time 

_dos_getdate, _dos_setdate, _dos_settime, stime, time 
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_dos_getvect 



_dos_getvect 



Function 
Syntax 



Remarks 



Return value 
See also 



dos.h 



Gets interrupt vector. 

void interrupt (*_dos_getvect (unsigned interruptno) 
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■ 











Every processor of the 8086 family includes a set of interrupt vectors, 
numbered to 255. The 4-byte value in each vector is actually an address, 
which is the location of an interrupt function. 

_dos_getvect reads the value of the interrupt vector given by interruptno and 
returns that value as a (far) pointer to an interrupt function. The value of 
interruptno can be from to 255. 

_dos_getvect returns the current 4-byte value stored in the interrupt vector 
named by interruptno. 

_disable, _enable, _dos_setvect 



_dos_open 



fcntl.h, share.h, dos.h 



Function 
Syntax 



Remarks 



Opens a file for reading or writing. 

unsigned _dos_open (const char *filename, unsigned of lags, int *handlep) 
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■ 
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_dos_open opens the file specified by filename, then prepares it for reading or 
writing, as determined by the value of oflags. The file is always opened in 
binary mode. _dos_open stores the file handle at the location pointed to by 
handlep. 

oflags uses the flags from the following two lists. Only one flag from the 
first list can be used (and one must be used); the remaining flags can be 
used in any logical combination. 

List 1 : Read/write flags 

0_RDONLY Open for reading. 
0_WRONLY Open for writing. 
0_RDWR Open for reading and writing. 
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_dos_open 



These symbolic 
constants are defined 
in fcntl.h and share.h. 



Return value 



The following additional values can be included in oflags (using an OR 
operation): 

List 2: Other access flags 



O.NOINHERIT 
SH COMPAT 



The file is not passed to child programs. 

Allow other opens with SH_COMPAT. The call will 

fail if the file has already been opened in any other 

shared mode. 
SH_DENYRW Only the current handle can have access to the file. 
SH_DENWR Allow only reads from any other open to the file. 

SH_DENYRD Allow only writes from any other open to the file. 
SH_DENYNO Allow other shared opens to the file, but not other 

SH_COMPAT opens. 

Only one of the SHJDENYxx values can be included in a single _dos_open. 
These file-sharing attributes are in addition to any locking performed on 
the files. 

The maximum number of simultaneously open files is defined by 
HANDLE_MAX. 

On successful completion, _dos_open returns 0, and stores the file handle at 
the location pointed to by handlep. The file pointer, which marks the current 
position in the file, is set to the beginning of the file. 

On error, _dos_open returns the operating system error code. The global 
variable errno is set to one of the following: 




See also 



EACCES 
EINVACC 
EMFILE 
ENOENT 



Permission denied 
Invalid access code 
Too many open files 
Path or file not found 



open, _rtl_read, sopen 



dos read 



io.h, dos.h 



Function 
Syntax 



Reads from file. 

unsigned ._dos_read(int handle, void far *buf, unsigned *nread) ; 
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■ 




■ 








■ 



Chapter 3, Run-time functions 



79 



dos read 



Remarks 



Return value 



_dos_read reads len bytes from the file associated with handle into buf. The 
actual number of bytes read is stored at the location pointed to by mead; 
when an error occurs, or the end-of-file is encountered, this number might 
be less than len. 

_dos_read does not remove carriage returns because it treats all files as 
binary files. 

handle is a file handle obtained from a _dos_creat, _dos_creatnew, or _dos_open 
call. 

On disk files, _dos_read begins reading at the current file pointer. When the 
reading is complete, the function increments the file pointer by the number 
of bytes read. On devices, the bytes are read directly from the device. 

The maximum number of bytes that _dos_read can read is UINTJviAX -1, 
because UINT_MAX is the same as -1, the error return indicator. 
UINT_MAX is defined in limits.h. 

On successful completion, _dos_read returns 0. Otherwise, the function 
returns the DOS error code and sets the global variable errno. 



See also 



EACCES 
EBADF 



Permission denied 
Bad file number 



_rtl_open, read, _rtl_write 



dos setdate 



See _dos_getdate. 



dos setdrive 



See _dos_getdrive. 



dos setfileattr 



See _dos_getfileattr. 
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dos settime 



dos setftime 



See _dos_getftime. 




dos settime 



See _dos_gettime. 



dos setvect 



dos.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Sets interrupt vector entry. 

void _dos_setvect (unsigned interruptno, void interrupt (*isr) 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 
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■ 











Every processor of the 8086 family includes a set of interrupt vectors, 
numbered to 255. The 4-byte value in each vector is actually an address, 
which is the location of an interrupt function. 

_dos_setvect sets the value of the interrupt vector named by interruptno to a 
new value, isr, which is a far pointer containing the address of a new 
interrupt function. The address of a C routine can be passed to isr only if 
that routine is declared to be an interrupt routine. 

If you use the prototypes declared in dos.h, pass the address of an interrupt 
function to _dos_setvect in any memory model. 

None. 

_dos_getvect 



dostounix 



dos.h 



Function 
Syntax 



Converts date and time to UNIX time format. 

long dostounix (struct date *d, struct time *t); 
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- 
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■ 
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dostounix 



Remarks 

Return value 
See also 



dostounix converts a date and time as returned from' getdate and gettime into 
UNIX time format, d points to a date structure, and t points to a time 
structure containing valid date and time information. 

The date and time must not be earlier than or equal to Jan 1 1980 00:00:00. 

UNIX version of current date and time parameters: number of seconds 
since 00:00:00 on January 1, 1970 (GMT). 

getdate, gettime, unixtodos 



dos write 



dos.h 



Function 
Syntax 



Writes to a file. 

unsigned _dos_write(int handle, const void far *buf, unsigned len, 

unsigned *nwritten) ; 



Remarks 



Return value 



See also 
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OS/2 


■ 




■ 
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_dos_write writes len bytes from the buffer pointed to by the far pointer 

buf to the file associated with handle. _dos_write does not translate a linefeed 
character (LF) to a CR/LF pair because it treats all files as binary data. 

The actual number of bytes written is stored at the location pointed to by 
nwritten. If the number of bytes actually written is less than that requested, 
the condition should be considered an error and probably indicates a full 
disk. For disk files, writing always proceeds from the current file pointer. 
On devices, bytes are directly sent to the device. 

On successful completion, _dos_write returns 0. Otherwise, it returns the 
operating system error code and the global variable errno is set to one of the 
following values: 



EACCES 
EBADF 



Permission denied 
Bad file number 



_dos_open, _dos_creat, _dos_read 



dup 



io.h 



Function 
Syntax 



Duplicates a file handle. 

int dup(int handle); 



82 



Library Reference 



dup 



Remarks 



Return value 
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■ 
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■ 



dup creates a new file handle that has the following in common with the 
original file handle: 

■ Same open file or device 

■ Same file pointer (that is, changing the file pointer of one changes the 
other) 

■ Same access mode (read, write, read /write) 

handle is a file handle obtained from a _rtl_creat, creat, _rtl_open, open, dup, 
or dup2 call. 

Upon successful completion, dup returns the new file handle, a nonnegative 
integer; otherwise, dup returns -1. 

In the event of error, the global variable errno is set to one of the following 
values: 




See also 



EBADF Bad file number 
EMFILE Too many open files 

_rtl_close, close, _rtl_creat, creat, creatnew, creattemp, dup2, fopen, _rtl_open, 
open 



dup2 



io.h 



Function 
Syntax 



Remarks 



Duplicates a file handle (oldhandle) onto an existing file handle (newhandle). 

int dup2(int oldhandle, int newhandle); 
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dup2 creates a new file handle that has the following in common with the 
original file handle: 

■ Same open file or device 

■ Same file pointer (that is, changing the file pointer of one changes the 
other) 

■ Same access mode (read, write, read/write) 

dupl creates a new handle with the value of newhandle. If the file associated 
with newhandle is open when dupl is called, the file is closed. 
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dup2 



newhandle and oldhandle are file handles obtained from a creat, open, dup, or 
dup2 call. 

Return value dup2 returns on successful completion, -1 otherwise. 

In the event of error, the global variable errno is set to one of the following 
values: 



See also 



EBADF Bad file number 
EMFILE Too many open files 

_rtl_close, close, _rtl_creat, creat, creatnew, creattemp, dup, fopen, _rtl_open, open 



ecvt 



stdlib.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Converts a floating-point number to a string. 

char *ecvt (double value, int ndig, int *dec, int *sign) ; 
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ecvt converts value to a null-terminated string of ndig digits, starting with 
the leftmost significant digit, and returns a pointer to the string. The 
position of the decimal point relative to the beginning of the string is stored 
indirectly through dec (a negative value for dec means that the decimal lies 
to the left of the returned digits). There is no decimal point in the string 
itself. If the sign of value is negative, the word pointed to by sign is nonzero; 
otherwise, it's 0. The low-order digit is rounded. 

The return value of ecvt points to static data for the string of digits whose 
content is overwritten by each call to ecvt and fcvt . 

fcvt, gcvt, sprint f 



emit 



dos.h 



Function 
Syntax 



Inserts literal values directly into code. 

void : emit (argument,. . . . ) ; 
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■ 


■ - 






■ 
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emit 



Description emit is an inline function that lets you insert literal values directly into 

object code as it is compiling. It is used to generate machine language 
instructions without using inline assembly language or an assembler. 

Generally the arguments of an emit call are single-byte machine 

instructions. However, because of the capabilities of this function, more 
complex instructions, complete with references to C variables, can be 
constructed. 

fc^ You should use this function only if you are familiar with the machine 

language of the 80x86 processor family. You can use this function to place 
arbitrary bytes in the instruction code of a function; if any of these bytes is 
incorrect, the program misbehaves and can easily crash your machine. 
Borland C++ does not attempt to analyze your calls for correctness in any 
way. If you encode instructions that change machine registers or memory, 
Borland C++ will not be aware of it and might not properly preserve 
registers, as it would in many cases with inline assembly language (for 
example, it recognizes the usage of SI and DI registers in inline 
instructions). You are completely on your own with this function. 

You must pass at least one argument to emit ; any number can be 

given. The arguments to this function are not treated like any other 

function call arguments in the language. An argument passed to emit 

will not be converted in any way. 

There are special restrictions on the form of the arguments to emit . 

Arguments must be in the form of expressions that can be used to initialize 
a static object. This means that integer and floating-point constants and the 
addresses of static objects can be used. The values of such expressions are 
written to the object code at the point of the call, exactly as if they were 
being used to initialize data. The address of a parameter or auto variable, 
plus or minus a constant offset, can also be used. For these arguments, the 
offset of the variable from BP is stored. 

The number of bytes placed in the object code is determined from the type 
of the argument, except in the following cases: 

■ If a signed integer constant (that is 0x90) appears that fits within the 
range of to 255, it is treated as if it were a character. 

■ If the address of an auto or parameter variable is used, a byte is written if 
the offset of the variable from BP is between -128 and 127; otherwise, a 
word is written. 

Simple bytes are written as follows: 

_ _emit_ _(0x90) ; 
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Return value 



If you want a word written, but the value you are passing is under 255, 
simply cast it to unsigned using one of these methods: 

_ _emit_ _(0xB8, (unsigned) 17 ) ; 
_ _emit_ _(0xB8, 17u) ; 

Two- or four-byte address values can be forced by casting an address to 
void near * or void far *, respectively. 

None. 



enable, .enable 



See disable. 



endthread 



process.h 



Function 
Syntax 



Terminates execution of a thread. 

void _endthread (void); 
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ANSI C++ 
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Remarks 



Return value 
See also 



The _endthread function terminates the currently executing thread. The 
thread must have been started by an earlier call to Jbeginthread. 

This function is available in the multithread libraries; it is not in the single- 
thread libraries. 

The function does not return a value. 

Jbeginthread 



eof 



io.h 



Function 
Syntax 



Checks for end-of-file. 

int eof (int handle) ; 
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eof 



Remarks 
Return value 



See also 



eof determines whether the file associated with handle has reached end-of- 
file. 

If the current position is end-of-file, eof returns the value 1; otherwise, it 
returns 0. A return value of -1 indicates an error; the global variable errno is 
set to 

EBADF Bad file number 
clearerr, feof, f error, perror 




execl, execle, execlp, execlpe, execv, execve, execvp, execvpe process.h 



Function 
Syntax 



Loads and runs other programs. 

int execl (char *path, char *argO *argl, .. 
int execle (char *path, char *argO, *argl, 

int execlp (char *path, char *argO,*argl, . 
int execlpe (char *path, char *argO, *argl, 



*argn, NULL) ; 
, , *argn, NULL, char **env) ; 



k argn, NULL); 

, *argn, NULL, char **env) ; 



int execvfchar *path, char *argv[]); 

int execvefchar *path, char *argv[], char **env) ; 

int execvpfchar *path, char *argv[]); 

int execvpe(char *path, char *argv[], char **env); 
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Remarks 



The functions in the exec. . . family load and run (execute) other programs, 
known as child processes. When an exec. . . call succeeds, the child process 
overlays the parent process. There must be sufficient memory available for 
loading and executing the child process. 

path is the file name of the called child process. The exec. . . functions search 
for path using the standard search algorithm: 

■ If no explicit extension is given, the functions search for the file as given. 
If the file is not found, they add .EXE and search again. If not found, they 
add .COM and search again. If still not found, they add .BAT and search 
once more. The command processor COMSPEC is used to run the 
executable file. 

■ If an explicit extension or a period is given, the functions search for the 
file exactly as given. 
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execl, execle, execlp, execlpe, execv, execve, execvp, execvpe 



The suffixes /, v, p, and e added to the exec. . . "family name" specify that the 
named function operates with certain capabilities. 

■ / specifies that the argument pointers (argO, argl, ..., argn) are passed as 
separate arguments. Typically, the / suffix is used when you know in 
advance the number of arguments to be passed. 

■ v specifies that the argument pointers (argv[0] ..., argln]) are passed as an 
array of pointers. Typically, the v suffix is used when a variable number 
of arguments is to be passed. 

■ p specifies that the function searches for the file in those directories 
specified by the PATH environment variable (without the p suffix, the 
function searches only the current working directory). If the path parame- 
ter does not contain an explicit directory, the function searches first the 
current directory, then the directories set with the PATH environment 
variable. 

■ e specifies that the argument env can be passed to the child process, 
letting you alter the environment for the child process. Without the e 
suffix, child processes inherit the environment of the parent process. 

Each function in the exec. . . family must have one of the two argument- 
specifying suffixes (either / or v). The path search and environment 
inheritance suffixes (p and e) are optional; for example, 

■ execl is an exec. . . function that takes separate arguments, searches only 
the root or current directory for the child, and passes on the parent's 
environment to the child. 

■ execvpe is an exec. . . function that takes an array of argument pointers, 
incorporates PATH in its search for the child process, and accepts the env 
argument for altering the child's environment. 

The exec. . . functions must pass at least one argument to the child process 
(argO or argv[0]); this argument is, by convention, a copy of path. (Using a 
different value for this Oth argument won't produce an error.) 

path is available for the child process. 

When the / suffix is used, argO usually points to path, and argl, ..., argn 
point to character strings that form the new list of arguments. A mandatory 
null following argn marks the end of the list. 

When the e suffix is used, you pass a list of new environment settings 
through the argument env. This environment argument is an array of 
character pointers. Each element points to a null-terminated character 
string of the form 

envvar = value 
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execl, execle, execlp, execlpe, execv, execve, execvp, execvpe 



Return value 



where envvar is the name of an environment variable, and value is the string 
value to which envvar is set. The last element in env is null. When env is 
null, the child inherits the parents' environment settings. 

The combined length of argO + argl + ... + argn (or of argv[0] + argv[l] + ... 
+ argn[n]), including space characters that separate the arguments, must be 
less than 128 bytes for a 16-bit application, or 260 bytes for Win32 
application. Null characters are not counted. 

When an exec. . . function call is made, any open files remain open in the 
child process. 

If successful, the exec. . . functions do not return. On error, the exec. . . 
functions return -1, and the global variable errno is set to one of the 
following values: 




See also 



EACCES Permission denied 

EMFILE Too many open files 

ENOENT Path or file name not found 

ENOEXEC Exec format error 

ENOMEM Not enough memory 

abort, atexit, _exit, exit, Jpreset, searchpath, spawn.. ., system 



exit 



stdlib.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Terminates program. 

void _exit(int status); 
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_exit terminates execution without closing any files, flushing any output, or 
calling any exit functions. 

The calling process uses status as the exit status of the process. Typically a 
value of is used to indicate a normal exit, and a nonzero value indicates 
some error. 

None. 

abort, atexit, exec. . ., exit, spawn.. . 
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exit 



exit 

Function 
Syntax 



Remarks 



stdlib.h 



Return value 
See also 



Terminates program. 

void exit(int status); 
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exit terminates the calling process. Before termination, all files are closed, 
buffered output (waiting to be output) is written, and any registered "exit 
functions" (posted with atexit) are called. 

status is provided for the calling process as the exit status of the process. 
Typically a value of is used to indicate a normal exit, and a nonzero value 
indicates some error. It can be, but is not required, to be set with one of the 
following: 

EXIT_FAILURE Abnormal program termination; signal to operating 

system that program has terminated with an error 
EXIT_SUCCESS Normal program termination 

None. 

abort , atexit, exec ..., _exit, keep, signal, spawn ... 



exp, expl 



math.h 



Function 
Syntax 



Remarks 



Return value 



exp 
expl 



Calculates the exponential e to the x. 

double exp (double x) ; 

long double expl (long double x) ; 
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exp calculates the exponential function e x . 

expl is the long double version; it takes a long double argument and returns 
a long double result. 

This function can be used with bed and complex types. 

exp returns e x . 
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exp, expl 



See also 



Sometimes the arguments passed to these functions produce results that 
overflow or are incalculable. When the correct value overflows, exp returns 
the value HUGE_VAL and expl returns _LHUGE_VAL. Results of exces- 
sively large magnitude cause the global variable errno to be set to 

ERANGE Result out of range 

On underflow, these functions return 0.0, and the global variable errno is 
not changed. Error handling for these functions can be modified through 
the functions jnatherr and jnatherrl. 

frexp, Idexp, log, loglO, jnatherr, pow, powlO, sqrt 




.expand 



malloc.h 



Function 
Syntax 



Remarks 



Return value 



See also 



Grows or shrinks a heap block in place. 

void *_expand(void *block, size_t size); 
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This function attempts to change the size of an allocated memory block 
without moving the block's location in the heap. The data in the block are 
not changed, up to the smaller of the old and new sizes of the block. The 
block must have been allocated earlier with malloc, calloc, or realloc, and 
must not have been freed. 

If _expand is able to resize the block without moving it, _expand returns a 
pointer to the block, whose address is unchanged. If _expand is unsuccess- 
ful, it returns a NULL pointer and does not modify or resize the block. 

calloc, malloc, realloc 



tabs, fabsl 



math.h 



Function 
Syntax 



tabs 
fabsl 



Returns the absolute value of a floating-point number. 

double fabs (double x) ; 

long double fabsl (long double x) ; 
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tabs, fabsl 



Remarks fobs calculates the absolute value of x, a double, fabsl is the long double 

version; it takes a long double argument and returns a long double result. 

Return value jabs and fabsl return the absolute value of x. 

See also a bs, cabs, labs 



farcalloc 



alloc.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Allocates memory from the far heap. 

void far *farcalloc (unsigned long nunits, unsigned long unitsz); 
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farcalloc allocates memory from the far heap for an array containing nunits 
elements, each unitsz bytes long. 

For allocating from the far heap, note that 

■ All available RAM can be allocated. 

■ Blocks larger than 64K can be allocated. 

■ Far pointers (or huge pointers if blocks are larger than 64K) are used to 
access the allocated blocks. 

In the compact and large memory models, farcalloc is similar, though not 
identical, to calloc. It takes unsigned long parameters, while calloc takes 
unsigned parameters. 

farcalloc returns a pointer to the newly allocated block, or NULL if not 
enough space exists for the new block. 

calloc, farfree, farmalloc, malloc 



farfree 



alloc.h 



Function 
Syntax 



Remarks 



Frees a block from far heap. 

void farfree (void far * block); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 











farfree releases a block of memory previously allocated from the far heap. 
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farfree 



Return value 
See also 

farmalloc 



In the small and medium memory models, blocks allocated by farmalloc 
cannot be freed with normal free, and blocks allocated with malloc cannot be 
freed with farfree. In these models, the two heaps are completely distinct. 

None. 

farcalloc, farmalloc 

alloc.h 




Function 
Syntax 



Remarks 



Return value 
See also 



Allocates from far heap. 

void far *farmalloc (unsigned long nbytes); 
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farmalloc allocates a block of memory nbytes bytes long from the far heap. 
For allocating from the far heap, note that 

■ All available RAM can be allocated. 

■ Blocks larger than 64K can be allocated. 

■ Far pointers are used to access the allocated blocks. 

In the compact and large memory models, farmalloc is similar though not 
identical to malloc. It takes unsigned long parameters, while malloc takes 
unsigned parameters. 

farmalloc returns a pointer to the newly allocated block, or NULL if not 
enough space exists for the new block. 

farcalloc, farfree, farrealloc, malloc 



farrealloc 



alloc.h 



Function 
Syntax 



Remarks 



Adjusts allocated block in far heap. 

void far * farrealloc (void far *oldblock, unsigned long nbytes) 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 











farrealloc adjusts the size of the allocated block to nbytes, copying the 
contents to a new location, if necessary. 
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farrealloc 



Return value 



See also 



For allocating from the far heap, note that 

■ All available RAM can be allocated. 

■ Blocks larger than 64K can be allocated. 

■ Far pointers are used to access the allocated blocks. 

farrealloc returns the address of the reallocated block, which might be 
different than the address of the original block. If the block cannot be 
reallocated, farrealloc returns NULL. 

farmalloc, realloc 



fclose 



stdio.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Closes a stream. 

int fclose (FILE *stream) ; 
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fclose closes the named stream. All buffers associated with the stream are 
flushed before closing. System-allocated buffers are freed upon closing. 
Buffers assigned with setbuf or setvbuf are not automatically freed. (But if 
setvbuf is passed null for the buffer pointer, it will free it upon close.) 

fclose returns on success. It returns EOF if any errors were detected. 

close, fcloseall, fdopen, fflush; flushall, fopen, freopen 



fcloseall 



stdio.h 



Function 
Syntax 



Closes open streams. 

int fcloseall (void) ; 
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Remarks 



fcloseall closes all open streams except stdin, stdout, stdprn, stderr, and 
stdaux. stdprn and stdaux streams are not available on OS/2 and Win32. 
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fcloseall 



Return value 
See also 



fcloseall returns the total number of streams it closed. It returns EOF if any 
errors were detected. 

fclose, fdopen, flushall, fopen, freopen 



fcvt 



stdlib.h 




Function 
Syntax 



Remarks 



Return value 
See also 



Converts a floating-point number to a string. 

char *fcvt(double value, int ndig, int *dec, int *sign) ; 
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fcvt converts value to a null-terminated string digit, starting with the 
leftmost significant digit, with ndig digits to the right of the decimal point. 
fcvt then returns a pointer to the string. The position of the decimal point 
relative to the beginning of the string is stored indirectly through dec (a 
negative value for dec means to the left of the returned digits). There is no 
decimal point in the string itself. If the sign of value is negative, the word 
pointed to by sign is nonzero; otherwise, it is 0. 

The correct digit has been rounded for the number of digits to the right of 
the decimal point specified by ndig. 

The return value oifcvt points to static data whose content is overwritten 
by each call to fcvt and ecvt . 

ecvt, gcvt, sprintf 



fdopen 



stdio.h 



Function 
Syntax 



Remarks 



Associates a stream with a file handle. 

FILE *fdopen(int handle, char *type) ; 
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fdopen associates a stream with a file handle obtained from exeat, dup, dup2, 
or open. The type of stream must match the mode of the open handle. 

The type string used in a call to fdopen is one of the following values: 
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fdopen 



Value Description 

r Open for reading only. 

w Create for writing. 

a Append; open for writing at end-of-file, or create for writing if the file does not exist. 

r+ Open an existing file for update (reading and writing). 

w+ Create a new file for update. 

a+ Open for append; open (or create if the file does not exist) for update at the end of 
the file. 



Return value 
See also 



To specify that a given file is being opened or created in text mode, append 
a t to the value of the type string (rt, zu+t, and so on); similarly, to specify 
binary mode, append a & to the type string (wb, a+b, and so on). 

If a t or b is not given in the type string, the mode is governed by the global 
variable Jmode. If Jmode is set to 0_BINARY, files will be opened in binary 
mode. If Jmode is set to 0_TEXT, they will be opened in text mode. These 
0_. . . constants are defined in fcntl.h. 

When a file is opened for update, both input and output can be done on the 
resulting stream. However, output cannot be directly followed by input 
without an intervening fseek or rewind, and input cannot be directly 
followed by output without an intervening fseek, rewind, or an input that 
encounters end-of-file. 

On successful completion, fdopen returns a pointer to the newly opened 
stream. In the event of error, it returns NULL. 

fclose, fopen, freopen, open 



feof 



stdio.h 



Function 
Syntax 



Remarks 



Detects end-of-file on a stream. 

int feof (FILE *stream) ; 
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feof is a macro that tests the given stream for an end-of-file indicator. Once 
the indicator is set, read operations on the file return the indicator until 
rewind is called, or the file is closed. 
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feof 



Return value 
See also 

terror 

Function 
Syntax 

Remarks 

Return value 
See also 



The end-of-file indicator is reset with each input operation. 

feof returns nonzero if an end-of-file indicator was detected on the last input 
operation on the named stream, and if end-of-file has not been reached. 

clearerr, eof, ferror, perror 

stdio.h 

Detects errors on stream. 

int ferror(FILE * stream) ; 
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ferror is a macro that tests the given stream for a read or write error. If the 
stream's error indicator has been set, it remains set until clearerr or rewind is 
called, or until the stream is closed. 

ferror returns nonzero if an error was detected on the named stream. 

clearerr, eof, feof, fopen, gets, perror 



fflush 



stdio.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Flushes a stream. 

int fflush(FILE *stream) ; 
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If the given stream has buffered output, fflush writes the output for stream 
to the associated file. 

The stream remains open after fflush has executed, fflush has no effect on an 
unbuffered stream. 

fflush returns on success. It returns EOF if any errors were detected. 

f close, flushall, setbuf, setvbuf 
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fgetc 



fgetc 

Function 
Syntax 



Remarks 
Return value 

See also 

fgetchar 



stdio.h 



Gets character from stream. 

int fgetc (FILE * stream) ; 
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fgetc returns the next character on the named input stream. 

On success, fgetc returns the character read, after converting it to an int 
without sign extension. On end-of-file or error, it returns EOF. 

fgetchar, fputc, getc, getch, getchar, getche, ungetc, ungetch 



stdio.h 



Function 
Syntax 



Remarks 

Return value 
See also 

fgetpos 



Gets character from stdin. 

int fgetchar (void) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 






■ 



fgetchar returns the next character from stdin. It is defined as fgetc(stdin). 
For Win32s or Win32 GUI applications, stdin must be redirected. 

On success, fgetchar returns the character read, after converting it to an int 
without sign extension. On end-of-file or error, it returns EOF. 

fgetc, fputchar, freopen, getchar 

stdio.h 



Function 
Syntax 



Gets the current file pointer. 

int fgetpos (FILE *stream, fpos_t *pos); 
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Library Reference 



fgetpos 



Remarks 



Return value 



See also 



fgetpos stores the position of the file pointer associated with the given 
stream in the location pointed to by pos. The exact value is unimportant; its 
value is opaque except as a parameter to subsequent fsetpos calls. 

On success, fgetpos returns 0. On failure, it returns a nonzero value and sets 
the global variable errno to 



EBADF 
EINVAL 

fseek, fsetpos, ftell, tell 



Bad file number 
Invalid number 




fgets 



stdio.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Gets a string from a stream. 

char '* fgets (char *s, int n, FILE * stream) ; 
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fgets reads characters from stream into the string s. The function stops 
reading when it reads either n - 1 characters or a newline character, which- 
ever comes first, fgets retains the newline character at the end of s. A null 
byte is appended to s to mark the end of the string. 

On success, fgets returns the string pointed to by s; it returns NULL on 
end-of-file or error. 

cgets,fputs,gets 



filelength 



io.h 



Function 
Syntax 



Remarks 



Gets file size in bytes. 

long filelength (int handle); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 






■ 



filelength returns the length (in bytes) of the file associated with handle. 
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filelength 



Return value 



See also 



On success, filelength returns a long value, the file length in bytes. On error, 
it returns -1 and the global variable errno is set to 

EBADF Bad file number 
fopen, Iseek, open 



fileno 



stdio.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Gets file handle. 

int fileno (FILE *stream) ; 
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fileno is a macro that returns the file handle for the given stream. If stream 
has more than one handle, fileno returns the handle assigned to the stream 
when it was first opened. 

fileno returns the integer file handle associated with stream. 

fdopen, fopen, freopen 



findfirst 



dir.h 



Function 
Syntax 



Remarks 



Searches a disk directory. 

int findfirst (const char *pathname, struct ffblk *ffblk, int attrib) 
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findfirst begins a search of a disk directory for files specified by attributes or 
wildcards. 

pathname is a string with an optional drive specifier, path, and file name of 
the file to be found. Only the file name portion can contain wildcard match 
characters (such as ? or *). If a matching file is found, the ffblk structure is 
filled with the file-directory information. - 
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Tincmrsi 



The format of the structure ffblk is as follows: 




struct ffblk { 








char ff_reserved[21] ; 


/* 


reserved by DOS */ 


char ff_attrib; 




/* 


attribute found */ 


int ff_ftime; 




/* 


file time */ 


int ff_fdate; 




/* 


file date */ 


long ff_fsize; 




/* 


file size ■*/ 


char ff_name[13] ; 




/* 


found file name ■*/ 


struct ffblk { 








long ff. 


.reserved; 




long ff. 


.fsize; 




/*. file size */ 


unsigned long ff. 


.attrib; 




/* attribute found *'/ 


unsigned short ff. 


.ftime; 




/* file time */ 


unsigned short ff. 


.fdate; 




/* file date */ 


char ff. 


.name [256] ; 


/* found file name */ 




attrib is a file-attribute byte used in selecting eligible files for the search. 
attrib should be selected from the following constants defined in dos.h: 



FA_RDONLY Read-only attribute 



FA_HIDDEN 
FA_SYSTEM 
FA_LABEL 
FA_DIREC 
FA ARCH 



Hidden file 
System file 
Volume label 
Directory 
Archive 



A combination of constants can be ORed together. 

For more detailed information about these attributes, refer to your operat- 
ing system reference manuals. 

Note that ffjtime and ffjdate contain bit fields for referring to the current 
date and time. The structure of these fields was established by the operat- 
ing system. Both are 16-bit structures divided into three fields. 



ffjtime: 

Bits to 4 

Bits 5 to 10 
Bits 11 to 15 

ffjdate-. 

Bits 0-4 
Bits 5-8 
Bits 9-15 



The result of seconds divided by 2 (for example, 10 here 

means 20 seconds) 

Minutes 

Hours 

Day 

Month 

Years since 1980 (for example, 9 here means 1989) 
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iinunrsi 



Return value 



See also 



The structure ft ime declared in io.h uses time and date bit fields similar in 
structure to ffjtime, and ffjdate. 

findfirst returns on successfully finding a file matching the search 
pathname. When no more files can be found, or if there is some error in the 
file name, -1 is returned, and the global variable errno is set to 

ENOENT Path or file name not found 

and _doserrno is set to one of the following values: 

ENMFILE No more files 

ENOENT Path or file name not found 

findnext, getftime, setftime 



findnext 



dir.h 



Function 
Syntax 



Remarks 



Return value 



Continues findfirst search. 

int findnext (struct ffblk *ffblk); 
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findnext is used to fetch subsequent files that match the pathname given in 
findfirst. ffblk is the same block filled in by the findfirst call. This block 
contains necessary information for continuing the search. One file name for 
each call to findnext will be returned until no more files are found in the 
directory matching the pathname. 

findnext returns on successfully finding a file matching the search 
pathname. When no more files can be found, or if there is some error in the 
file name, -1 is returned, and the global variable errno is set to 



See also 



ENOENT Path or file name not found 
and _doserrno is set to one of the following values: 
ENMFILE No more files 



ENOENT 
findfirst 



Path or file name not found 
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floor, floorl 



floor, floorl 

Function 
Syntax 



Remarks 
Return value 
See also 



floor 
floorl 



math.h 



Rounds down. 

double floor(double x) ; 

long double floorl (long double x) ; 
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floor finds the largest integer not greater than x. floorl is the long double 
version; it takes a long double argument and returns a long double result. 

floor returns the integer found as a double, floorl returns the integer found 
as a long double. 

ceil, fmod 



flushall 



stdio.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Flushes all streams. 

int flushall (void) ; 
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flushall clears all buffers associated with open input streams, and writes all 
buffers associated with open output streams to their respective files. Any 
read operation following flushall reads new data into the buffers from the 
input files. Streams stay open after flushall executes. 

flushall returns an integer, the number of open input and output streams. 

f close, fcloseall, fflush 



Jmemccpy 



See memccpy. 



Chapter 3, Run-time functions 



103 



fmemchr 



fmemchr 



.fmemcmp 



See memchr. 



Jmemcpy 



See memcmp. 



Jmemicmp 



See memcpy. 



See memicmp. 



fmemmove 



See memmove. 



fmemset 



See memset. 



fmod, fmodl 



math.h 



Function 
Syntax 



Calculates x modulo y, the remainder of x/y. 

double fmod(double x, double y) ; 

long double fmodl (long double x, long double y) ; 



fmod 
fmodl 
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fmod, fmodl 



Remarks 

Return value 
See also 

fmovmem 



fmod calculates x modulo y (the remainder /, where x = ay + f for some 
integer a and < / < y). fmodl is the long double version; it takes long 
double arguments and returns a long double result. 

fmod and fmodl return the remainder /, where x = ay + f (as described). 
Where y = 0, fmod and fmodl return 0. 

ceil, floor, modf 




See movmem. 



fnmerge 



dir.h 



Function 
Syntax 



Remarks 



Builds a path from component parts. 

void fnmerge (char *path, const char *drive, const char *dir, const char *name, 
const char *ext) ; 
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fnmerge makes a path name from its components. The new path name is 

X:\DIR\SUBDIR\NAME.EXT 

where 



Return value 
See also 



drive 


= 


X: 


dir 


= 


\DIR\SUBDIR\ 


name 


= 


NAME 


ext 


= 


.EXT 



fnmerge assumes there is enough space in path for the constructed path 
name. The maximum constructed length is MAXPATH. MAXPATH is 
defined in dir.h. 

fnmerge and fnsplit are invertible; if you split a given path with fnsplit, then 
merge the resultant components with fnmerge, you end up with path. 

None. 

fnsplit 
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fnsplit 



fnsplit 

Function 
Syntax 



Remarks 



dir.h 



Splits a full path name into its components. 

int fnsplit (const char *path, char *drive, char *dir, char *name, char *ext) 
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fnsplit takes a file's full path name (path) as a string in the form 

X:\DIR\SUBDIR\NAME.EXT 

and splits path into its four components. It then stores those components in 
the strings pointed to by drive, dir, name, and ext. (All five components must 
be passed, but any of them can be a null, which means the corresponding 
component will be parsed but not stored.) 

The maximum sizes for these strings are given by the constants MAXDRIVE, 
MAXDIR, MAXPATH, MAXFILE, and MAXEXT (defined in dir.h), and each size 
includes space for the null character. 



Constant 


Max 
16-bit 


Max 
32-bit 


String 


MAXPATH 

MAXDRIVE 

MAXDIR 

MAXFILE 

MAXEXT 


80 
3 

66 
9 
5 


260 
3 
260 
260 
260 


path 

drive; includes colon (:) 

dir, includes leading and trailing backslashes (\) 

name 

ext, includes leading dot (.) 



fnsplit assumes that there is enough space to store each non-null 
component. 

When fnsplit splits path, it treats the punctuation as follows: 

■ drive includes the colon (C:, A:, and so on). 

■ dir includes the leading and trailing backslashes ( \ BC\ include \, 
\source\, and so on). 

■ name includes the hie name. 

■ ext includes the dot preceding the extension (.C, .EXE, and so on). 

fnmerge and fnsplit are invertible; if you split a given path with fnsplit, then 
merge the resultant components with fnmerge, you end up with path. 
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fnsplit 



Return value 



fnsplit returns an integer (composed of five flags, defined in dir.h) 
indicating which of the full path name components were present in path. 
These flags and the components they represent are 



See also 



EXTENSION 

FILENAME 

DIRECTORY 

DRIVE 

WILDCARDS 

fnmerge 



An extension 

A file name 

A directory (and possibly subdirectories) 

A drive specification (see dir.h) 

Wildcards (* or ?) 




fopen 



stdio.h 



Function 
Syntax 



Remarks 



Opens a stream. 

FILE *fopen(const char *filename, const char *mode); 
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fopen opens the file named by filename and associates a stream with it. fopen 
returns a pointer to be used to identify the stream in subsequent 
operations. 

The mode string used in calls to fopen is one of the following values: 



Value 



Description 



r Open for reading only. 

w Create for writing. If a file by that name already exists, it will be overwritten. 

a Append; open for writing at end of file, or create for writing if the file does not exist. 

r+ Open an existing file for update (reading and writing). 

w+ Create a new file for update (reading and writing). If a file by that name already 

exists, it will be overwritten. 

a+ Open for append; open for update at the end of the file, or create if the file does not 

exist. 

To specify that a given file is being opened or created in text mode, append 
a t to the mode string (rt, w+t, and so on). Similarly, to specify binary mode, 
append a b to the mode string (w b, a+b, and so on), fopen also allows the t or 
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fopen 



Return value 
See also 



b to be inserted between the letter and the + character in the mode string; 
for example, rt+ is equivalent to r+t. 

If a t or b is not given in the mode string, the mode is governed by the global 
variable Jmode. If Jmode is set to 0_BINARY, files are opened in binary- 
mode. If Jmode is set to 0_TEXT, they are opened in text mode. These 0_. . . 
constants are defined in fcntl.h. 

When a file is opened for update, both input and output can be done on the 
resulting stream. However, output cannot be followed directly by input 
without an intervening fseek or rewind, and input cannot be directly 
followed by output without an intervening fseek, rewind, or an input that 
encounters end-of-file. 

On successful completion, fopen returns a pointer to the newly opened 
stream. In the event of error, it returns NULL. 

creat, dup, fclose, fdopen f error, Jmode (global variable), fread, freopen, fseek, 
fwrite, open, rewind, setbuf, setmode 



FP_OFF, FP_SEG 



dos.h 



Function 
Syntax 



Remarks 



Return value 



See also 



Gets a far address offset or segment. 

unsigned FP_0FF(void far *p) ; 
unsigned FP_SEG(void far *p); 
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The FPJDFF macro can be used to get or set the offset of the far pointer p. 
FP_SEG is a macro that gets or sets the segment value of the far pointer p. 
FPJDFF returns an unsigned integer value representing an offset value. 
FPJSEG returns an unsigned integer representing a segment value. 
MKJtP, movedata, segread 



Jpreset 



float.h 



Function 
Syntax 



Reinitializes floating-point math package. 

void _fpreset (void); 
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Jpreset 



Remarks 



Return value 
See also 
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Jpreset reinitializes the floating-point math package. This function is 
usually used in conjunction with system or the exec. . . or spawn.. . functions. 
It is also used to recover from floating-point errors before calling longjmp. 

If an 80x87 coprocessor is used in a program, a child process (executed by 
system or by an exec. . . or spawn.. . function) might alter the parent process' 
floating-point state. 

If you use an 80x87, take the following precautions: 

■ Do not call system or an exec. . . or spawn.. . function while a floating-point 
expression is being evaluated. 

■ Call Jpreset to reset the floating-point state after using system, exec. . ., or 
spawn.. . if there is any chance that the child process performed a 
floating-point operation with the 80x87. 

None. 

_clear87 , _control87, _status87 




fprintf 



stdio.h 



Function 
Syntax 



Remarks 



See printf for details 
on format specifiers. 

Return value 



See also 



Writes formatted output to a stream. 

int fprintf (FILE *stream, const char *format[, argument, .., 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 



fprintf accepts a series of arguments, applies to each a format specifier 
contained in the format string pointed to by format, and outputs the 
formatted data to a stream. There must be the same number of format 
specifiers as arguments. 

fprintf returns the number of bytes output. In the event of error, it returns 
EOF. 

cprintf, fscanf, printf, putc, sprintf 
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fputc 



fputc 

Function 
Syntax 



Remarks 

Return value 
See also 

fputchar 



stdio.h 



Puts a character on a stream. 

int fputc (int c, FILE *stream) ; 
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fputc outputs character c to the named stream. 

For Win32s or Win32 GUI applications, stdout must be redirected. 

On success, fputc returns the character c. On error, it returns EOF. 

fgetc,putc 



stdio.h 



Function 
Syntax 



Remarks 

Return value 
See also 

fputs 



Outputs a character on stdout. 

int fputchar (int c) ; 
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fputchar outputs character c to stdout. fputchar (c) is the same as 
fputcic, stdout). 

For Win32s or Win32 GUI applications, stdout must be redirected. 
On success, fputchar returns the character c. On error, it returns EOF. 
fgetchar, freopen, putchar 



stdio.h 



Function 
Syntax 



Outputs a string on a stream. 

int fputs(const char *s, FILE *stream) ; 
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fputs 



Remarks 

Return value 
See also 

fread 



fputs copies the null-terminated string s to the given output stream; it does 
not append a newline character, and the terminating null character is not 
copied. 

On successful completion, fputs returns a non-negative value. Otherwise, it 
returns a value of EOF. 



fgets, gets, puts 



stdio.h 




Function 
Syntax 



Remarks 

Return value 
See also 



Reads data from a stream. 

size_t fread(void *ptr, size_t size, size_t n, FILE *stream) ; 
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fread reads n items of data, each of length size bytes, from the given input 
stream into a block pointed to by ptr. 

The total number of bytes read is (n x size). 

On successful completion, fread returns the number of items (not bytes) 
actually read. It returns a short count (possibly 0) on end-of-file or error. 

fopen, fwrite, printf, read 



free 



stdlib.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Frees allocated block. 

void free (void *block) ; 
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free deallocates a memory block allocated by a previous call to calloc, malloc, 
or realloc. 

None. 

calloc, malloc, realloc, strdup 
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freopen 



freopen 

Function 
Syntax 



Remarks 



stdio.h 



Return value 
See also 



Associates a new file with an open stream. 

FILE * freopen (const char *filename, const char *mode, FILE *stream) 
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freopen substitutes the named file in place of the open stream. It closes 
stream, regardless of whether the open succeeds, freopen is useful for 
changing the file attached to stdin, stdout, or stderr. 

The mode string used in calls to fopen is one of the following values: 



Value 



Description 



r Open for reading only. 

w Create for writing. 

a Append; open for writing at end-of-file, or create for writing if the file does not exist. 

r+ Open an existing file for update (reading and writing). 

w+ Create a new file for update. 

a+ Open for append; open (or create if the file does not exist) for update at the end of 

the file. 

To specify that a given file is being opened or created in text mode, append 
a t to the mode string (rt, w+t, and so on); similarly, to specify binary mode, 
append a & to the mode string (wb, a+b, and so on). 

If a t or b is not given in the mode string, the mode is governed by the global 
variable Jmode. If Jmode is set to 0_BINARY, files are opened in binary 
mode. If Jmode is set to OJTEXT, they are opened in text mode. These 0_. . . 
constants are defined in fcntl.h. 

When a file is opened for update, both input and output can be done on the 
resulting stream. However, output cannot be directly followed by input 
without an intervening fseek or rewind, and input cannot be directly 
followed by output without an intervening fseek, rewind, or an input that 
encounters end-of-file. 

On successful completion, freopen returns the argument stream. In the event 
of error, it returns NULL. 

f close, fdopen, fopen, open, setmode 
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frexp, frexpl 



f rexp, frexpl 



Function 
Syntax 



Remarks 



Return value 
See also 



frexp 
frexpl 



math.h 



Splits a number into mantissa and exponent. 

double frexp (double x, int *exponent); 

long double frexpl (long double x, int *exponent); 
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frexp calculates the mantissa m (a double greater than or equal to 0.5 and 
less than 1) and the integer value n, such that x (the original double value) 
equals m x 2". frexp stores n in the integer that exponent points to. 

frexpl is the long double version; it takes a long double argument for x and 
returns a long double result. 

frexp and frexpl return the mantissa rri. Error handling for these routines can 
be modified through the functions jnatherr and jnatherrl. 

exp, Idexp, jnatherr, 



fscanf 



stdio.h 



Function 
Syntax 



Remarks 



See scant for details 
on format specifiers. 



Return value 



Scans and formats input from a stream. 

int fscanf (FILE *stream, const char *format[, address, ...]' 
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fscanf scans a series of input fields, one character at a time, reading from a 
stream. Then each field is formatted according to a format specifier passed 
to fscanf in the format string pointed to by format. Finally, fscanf stores the 
formatted input at an address passed to it as an argument following format. 
The number of format specifiers and addresses must be the same as the 
number of input fields. 

fscanf can stop scanning a particular field before it reaches the normal end- 
of-field character (whitespace), or it can terminate entirely for a number of 
reasons. See scanf for a discussion of possible causes. 

fscanf returns the number of input fields successfully scanned, converted, 
and stored; the return value does not include scanned fields that were not 
stored. 
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fscanf 



See also 



If fscanf attempts to read at end-of-file, the return value is EOF. If no fields 
were stored, the return value is 0. 

atof, cscanf, fprintf, printf, scanf, sscanf, vfscanf, vscanf, vsscanf 



fseek 



stdio.h 



Function 
Syntax 



Remarks 



Repositions a file pointer on a stream. 

int fseek(FILE *stream, long offset, int whence); 
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fseek sets the file pointer associated with stream to a new position that is 
offset bytes from the file location given by whence. For text mode streams, 
offset should be or a value returned by ft ell. 

whence must be one of the values 0, 1, or 2, which represent three symbolic 
constants (defined in stdio.h) as follows: 



Constant 



whence, File location 



Return value 



SEEK_SET 
SEEK_CUR 
SEEK END 



File beginning 

1 Current file pointer position 

2 End-of-file 



fseek discards any character pushed back using ungetc. fseek is used with 
stream I/O; for file handle I/O, use Iseek. 

After fseek, the next operation on an update file can be either input or 
output. 

fseek returns if the pointer is successfully moved and nonzero on failure. 

fseek might return a 0, indicating that the pointer has been moved success- 
fully, when in fact it has not been. This is because DOS, which actually 
resets the pointer, does not verify the setting, fseek returns an error code 
only on an unopened file or device. 

In the event of an error return, the global variable errno is set to one of the 
following values: 

EBADF Bad file pointer 

EINVAL Invalid argument 
ESPIPE Illegal seek on device 
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fseek 



See also 



fgetpos, fopen, fsetpos, ftell, Iseek, rewind, setbuf, tell 



fsetpos 



stdio.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Positions the file pointer of a stream. 

int fsetpos (FILE. *stream, const fpos_t *pos) ; 
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fsetpos sets the file pointer associated with stream to a new position. The 
new position is the value obtained by a previous call to fgetpos on that 
stream. It also clears the end-of-file indicator on the file that stream points to 
and undoes any effects of ungetc on that file. After a call to fsetpos, the next 
operation on the file can be input or output. 

On success, fsetpos returns 0. On failure, it returns a nonzero value and also 
sets the global variable errno to a nonzero value. 

fgetpos, fseek, ftell 



jsopen 



stdio.h, share.h 



Function 
Syntax 



Remarks 



Opens a stream with file sharing. 

FILE *_fsopen (const char *filename, const char *mode, int shflag) ; 
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Jsopen opens the file named by filename and associates a stream with it. 
Jsopen returns a pointer that is used to identify the stream in subsequent 
operations. 

The mode string used in calls to Jsopen is one of the following values: 



Mode 



Description 



r Open for reading only. 

w Create for writing. If a file by that name already exists, it will be overwritten. ; 

a Append; open for writing at end of file, or create for writing if the file does not exist. 
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Jsopen 



r+ 
w+ 



a+ 



Open an existing file for update (reading and writing). 

Create a new file for update (reading and writing). If a file by that name already 
exists, it will be overwritten. 

Open for append; open for update at the end of the file, or create if the file does not 
exist. 



To specify that a given file is being opened or created in text mode, append 
a t to the mode string (rt, zv+t, and so on). Similarly, to specify binary mode, 
append a & to the mode string (zvb, a+b, and so on). Jsopen also allows the t 
or b to be inserted between the letter and the + character in the mode string; 
for example, rt+ is equivalent to r+i. 

If a t or b is not given in the mode string, the mode is governed by the global 
variable Jmode. If Jmode is set to 0_BINARY, files are opened in binary 
mode. If Jmode is set to 0_TEXT, they are opened in text mode. These 0_. . . 
constants are defined in fcntl.h. 

When a file is opened for update, both input and output can be done on the 
resulting stream. However, output cannot be followed directly by input 
without an intervening fseek ox rewind, and input cannot be directly 
followed by output without an intervening fseek, rewind, or an input that 
encounters end-of-file. 

shflag specifies the type of file-sharing allowed on the file filename. Symbolic 
constants for shflag are defined in share.h. 



Value of shflag 



Description 



SH_COMPAT 

SH_DENYRW 

SH.DENYWR 

SH.DENYRD 

SH_DENYNONE 

SH DENYNO 



Sets compatibility mode 
Denies read/write access 
Denies write access 
Denies read access 
Permits read/write access 
Permits read/write access 



Return value 
See also 



On successful completion, Jsopen returns a pointer to the newly opened 
stream. In the event of error, it returns NULL. 

creat, _dos_open, dup, f close, fdopen, f error, Jmode (global variable), fopen, 
fread, freopen, fseek, fwrite, open, rewind, setbuf, setmode, sopen 



fstat, stat 



sys\stat.h 



Function 



Gets open file information. 
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fstat, stat 



Syntax 



Remarks 



int fstat (int handle, struct stat *statbuf); 
int stat (char *path, struct stat *statbuf); 
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fstat stores information in the stat structure about the file or directory 
associated with handle. 

stat stores information about a given file or directory in the stat structure. 
The name of the file is path. 

statbuf points to the stat structure (defined in sys\stat.h). That structure 
contains the following fields: 




stjnode Bit mask giving information about the file's mode 

st_dev Drive number of disk containing the hie, or file handle if the 
file is on a device 

stjdev Same as st_dev 

st_nlink Set to the integer constant 1 

st_size Size of the file in bytes 

st_atime Most recent access 

stjntime Same as st_atime 

st_ctime Same as st_atime 

The stat structure contains three more fields not mentioned here. They 
contain values that are meaningful only in UNIX. 

The stjnode bit mask that gives information about the mode of the open file 
includes the following bits: 

One of the following bits will be set: 

S_IFCHR If handle refers to a device. 

S_IFREG If an ordinary file is referred to by handle. 

One or both of the following bits will be set: 

S_IWRITE If user has permission to write to file. 
S_IREAD If user has permission to read to file. 

The HPFS and NTFS file-management systems make the following 
distinctions: 
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fstat, stat 



Return value 



See also 



st_atime Most recent access. 
stjntime Most recent modify. 
st_ctime Creation time. 

fstat and stat return if they successfully retrieved the information about 
the open file. On error (failure to get the information), these functions 
return -1 and set the global variable errno to 

EBADF Bad file handle 

access, chmod 



isir* 



string.h 



Function 
Syntax 



Remarks 

Note that when a far 

string function returns 

an int or sizej, the 

return is never 

modified by the far 

keyword. 

Return value 
See also 



Provides string operations in a large-code model. 

far string functions 
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The See also section below provides a list of string functions that have a far 
version. The far version of a string function is prefixed with _fstr. The 
behavior of a far string function is identical to the behavior of the standard 
function to which it corresponds. The only difference is that for a far string 
function, the arguments and return value (only when the return value is of 
type 'char far *' ) are each modified by the far keyword. The entry for each 
of the functions provides a description that applies to the far version. 

When an Jstr-type function returns a char pointer, the return is a far type. 

strcat, strchr, strcmp, strcpy, strcspn, strdup, stricmp, strlen, strlwr, strncat, 
strncmp, strncpy, strnicmp, strnset, strpbrk, strrchr, strrev, strset, strspn, strstr, 
strtok, strupr 



ftell 



stdio.h 



Function 
Syntax 



Returns the current file pointer. 

long int ftell (FILE *stream) ; 
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ftell 



Remarks 



Return value 



See also 



ftell returns the current file pointerior stream. The offset is measured in 
bytes from the beginning of the file (if the file is binary). The value returned 
by ftell can be used in a subsequent call to fseek. 

ftell returns the current file pointer position on success. It returns -1L on 
error and sets the global variable errno to a positive value. 

In the event of an error return, the global variable errno is set to one of the 
following values: 



EBADF 
ESPIPE 



Bad file pointer 
Illegal seek on device 

fgetpos, fseek, fsetpos, Iseek, rewind, tell 




ftime 



sys\timeb.h 



Function 
Syntax 



Remarks 



Stores current time in timeb structure. 

void ftime (struct timeb *buf) 
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On UNIX platforms, ftime is available only on System V systems. 

ftime determines the current time and fills in the fields in the timeb structure 
pointed to by buf. The timeb structure contains four fields: time, millitm, 
Jimezone, and dstflag: 

struct timeb { ■. ~ 

long time ; ■ , 

short millitm ; 

short _timezone ; 

short dstflag ; 
}; 

■ time provides the time in seconds since 00:00:00 Greenwich mean time 
(GMT), January 1, 1970. 

■ millitm is the fractional part of a second in milliseconds. 

■ _timezone is the difference in minutes between GMT and the local time. 
This value is computed going west from GMT. ftime gets this field from 
the global variable Jimezone, which is set by tzset. 

u dstflag is used to indicate whether daylight saving time will be taken into 
account during time calculations. 
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ftime 



^^ ftime calls tzset . Therefore, it isn't necessary to call tzset explicitly when you 
use ftime. 

Return value None. 

See also asctime, dime, gmtime, localtime, stime, time, tzset 



Jullpath 



stdlib.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Converts a path name from relative to absolute. 

char * _fullpath(char *buffer, const char *path, int buflen) 
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.Jullpath converts the relative path name in path to an absolute path name 
that is stored in the array of characters pointed to by buffer. The maximum 
number of characters that can be stored at buffer is buflen. The function 
returns NULL if the buffer isn't big enough to store the absolute path name, 
or if the path contains an invalid drive letter. 

If buffer is NULL, Jullpath allocates a buffer of up to _MAX_PATH charac- 
ters. This buffer should be freed using free when it is no longer needed. 
_MAX_PATH is defined in stdlib.h * 

If successful, the Jullpath function returns a pointer to the buffer containing 
the absolute path name. Otherwise, it returns NULL. 

jnakepath, _splitpath 



fwrite 



stdio.h 



Function 
Syntax 



Remarks 



Writes to a stream. 

size_t fwrite (const void *ptr, size_t size, size_t n, FILE *stream) 
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fwrite appends n items of data, each of length size bytes, to the given output 
file. The data written begins at ptr. The total number of bytes written is (n x 
size), ptr in the declarations is a pointer to any object. 
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fwrite 



Return value 



See also 



On successful completion, fwrite returns the number of items (not bytes) 
actually written. It returns a short count on error. 

fopen, fread 



gcvt 



stdlib.h 




Function 
Syntax 



Remarks 



Return value 
See also 



Converts floating-point number to a string. 

char *gcvt (double value, int ndec, char *buf); 
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gcvt converts value to a null-terminated ASCII string and stores the string in 
buf. It produces ndec significant digits in FORTRAN F format, if possible; 
otherwise, it returns the value in the printfE format (ready for printing). It 
might suppress trailing zeros. 

gcvt returns the address of the string pointed to by buf. 

ecvt,fcvt,sprintf 



geninterrupt 



dos.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Generates a software interrupt. 

void geninterrupt (int intr_num) ; 
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The geninterrupt macro triggers a software trap for the interrupt given by 
intrjnum. The state of all registers after the call depends on the interrupt 
called. 

Interrupts can leave registers in unpredictable states. 

None. 

bdos, bdosptr, disable, enable, getvect, int86, int86x, intdos, intdosx, intr 
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getc 



getc 

Function 
Syntax 



Remarks 
Return value 
See also 



stdio.h 



Gets character from stream. 

int getc (FILE *stream) ; 



DOS 
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ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 



getc is a macro that returns the next character on the given input stream and 
increments the stream's file pointer to point to the next character. 

On success, getc returns the character read, after converting it to an int 
without sign extension. On end-of-file or error, it returns EOF. 

fgetc, getch, getchar, getche, gets, putc, putchar, ungetc 



getcbrk 



dos.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Gets control-break setting. 

int getcbrk (void) ; 
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OS/2 


■ 




- 











getcbrk uses the DOS system call 0x33 to return the current setting of 
control-break checking. 

getcbrk returns if control-break checking is off, or 1 if checking is on. 

ctrlbrk, setcbrk 



getch 



conio.h 



Function 
Syntax 



Remarks 



Gets character from keyboard, does not echo to screen. 

int getch (void) ; 
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■ 






■ 






■ 



getch reads a single character directly from the keyboard, without echoing 
to the screen. 
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getch 



Return value 
See also 



This function should not be used in Win32s or Win32 GUI applications. 

getch returns the character read from the keyboard. 

cgets, cscanf, fgetc, getc, getchar, getche, getpass, kbhit, putch, ungetch 



getchar 



stdio.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Gets character from stdin. 

int getchar (void); 
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Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


" 




■ 


■ 


■ 


■ 



getchar is a macro that returns the next character on the named input stream 
stdin. It is defined to be getc(stdin). 

For Win32s or Win32 GUI applications, stdin must be redirected. 

On success, getchar returns the character read, after converting it to an int 
without sign extension. On end-of-file or error, it returns EOF. 

fgetc, fgetchar, freopen, getc, getch, getche, gets, putc, putchar, scanf, ungetc 



getche 



conio.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Gets character from the keyboard, echoes to screen. 

int getche (void) ; 
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Win 32 
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■ 






■ 






■ 



getche reads a single character from the keyboard and echoes it to the 
current text window using direct video or BIOS. 

This function should not be used in Win32s or Win32 GUI applications. 

getche returns the character read from the keyboard. 

cgets, cscanf, fgetc, getc, getch, getchar, kbhit, putch, ungetch 
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getcurdir 



getcurdir 

Function 
Syntax 



Remarks 



dir.h 



Return value 
See also 



Gets current directory for specified drive. 

int getcurdir (int drive, char directory) ; 



DOS 
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■ 




■ 


■ 






■ 



getcurdir gets the name of the current working directory for the drive 
indicated by drive, drive specifies a drive number (0 for default, 1 for A, and 
so on), directory points to an area of memory of length MAXDIR where the 
null-terminated directory name will be placed. The name does not contain 
the drive specification and does not begin with a backslash. 

getcurdir returns on success or -1 in the event of error. 

chdir, getcwd, getdisk, mkdir, rmdir 



getcwd 



dir.h 



Function 
Syntax 



Remarks 



Return value 



Gets current working directory. 

char *getcwd(char *buf, int buflen); 
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Win 16 
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■ 




■ 


■ 






■ 



getcwd gets the full path name (including the drive) of the current working 
directory, up to buflen bytes long and stores it in buf. If the full path name 
length (including the null character) is longer than buflen bytes, an error 
occurs. 

If buf is NULL, a buffer buflen bytes long is allocated for you with malloc. 
You can later free the allocated buffer by passing the return value of getcwd 
to the function free. 

getcwd returns the following values: 

■ If buf is not NULL on input, getcwd returns buf on success, NULL on 
error. 

■ If buf is NULL on input, getcwd returns a pointer to the allocated buffer. 
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getcwd 



In the event of an error return, the global variable errno is set to one of the 
following values: 



See also 



getdate 



ENODEV No such device 

ENOMEM Not enough memory to allocate a buffer (buf is NULL) 

ERANGE Directory name longer than buflen (buf is not NULL) 

chdir, getcurdir, _getdcwd, getdisk, mkdir, rmdir 




See _dos_getdate. 



.getdcwd 



direct.h 



Function 
Syntax 



Remarks 



Return value 



See also 



Gets current directory for specified drive. 

char * _getdcwd(int drive, char *buffer, int buflen); 
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■ 




■ 


■ 






■ 



_getdcwd gets the full path name of the working directory of the specified 
drive (including the drive name), up to buflen bytes long, and stores it in 
buffer. If the full path name length (including the null character) is longer 
than buflen, an error occurs. The drive is for the default drive, 1=A, 2=B, 
and so on. 

If buffer is NULL, _getdcwd allocates a buffer at leaslbuflen bytes long. You 
can later free the allocated buffer by passing the _getdcwd return value to 
the free function. 

If successful, _getdcwd returns a pointer to the buffer containing the current 
directory for the specified drive. Otherwise it returns NULL, and sets the 
global variable errno to one of the following values: 

ENOMEM Not enough memory to allocate a buffer {buffer is NULL) 
ERANGE Directory name longer than buflen (buffer is not NULL) 

chdir, getcwd, mkdir, rmdir 
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getdfree 



getdfree 

Function 
Syntax 



Remarks 



Return value 
See also 



dos.h 



Gets disk free space. 

void getdfree (unsigned char drive, struct dfree *dtable); 
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■ 




■ 


■ 






■ 



getdfree accepts a drive specifier in drive (0 for default, 1 for A, and so on) 
and fills the dfree structure pointed to by dtable with disk attributes. 

The dfree structure is defined as follows: 



struct dfree { 

unsigned df_avail; 

unsigned df_total; 

unsigned df_bsec; 

unsigned df_sclus; 
}; 



/* available clusters */ 

/* total clusters */ 

/* bytes per sector */ 

/* sectors per cluster */ 



getdfree returns no value. In the event of an error, df_sclus in the dfree 
structure is set to (unsigned) -1. 

getfat, getfatd 



getdisk, setdisk 



dir.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Gets or sets the current drive number. 

int getdisk (void) ; 

int setdisk(int drive); 
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■ 




■ 


■ 






■ 



getdisk gets the current drive number. It returns an integer: for A, 1 for B, 2 
for C, and so on. setdisk sets the current drive to the one associated with 
drive: for A, 1 for B, 2 for C, and so on. 

The setdisk function changes the current drive of the parent process. 

getdisk returns the current drive number, setdisk returns the total number of 
drives available. 

getcurdir, getcwd 
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getdta 

Function 
Syntax 



Remarks 



dos.h 



Return value 
See also 



Gets disk transfer address. 

char far *getdta(void) ; 
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■ 




■ 











getdta returns the current setting of the disk transfer address (DTA). 

In the small and medium memory models, it's assumed the segment is the 
current data segment. If you use C or C++ exclusively, this will be the case, 
but assembly routines can set the DTA to any hardware address. 

In the compact or large models, the address returned by getdta is the correct 
hardware address and can be located outside the program. 

getdta returns a far pointer to the current DTA. 

setdta 




getenv 



stdlib.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Gets a string from environment. 

char *getenv(const char *name) ; 
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■ 


■ 


■ 


■ 


■ 


■ 


■ 



getenv returns the value of a specified variable. On DOS and OS/2, name 
must be uppercase. On other systems, name can be either uppercase or low- 
ercase, name must not include the equal sign (=). If the specified 
environment variable does not exist, getenv returns a NULL pointer. 

To delete the variable from the environment, use getenv ( "name=" ) . 

Environment entries must not be changed directly. If you want to change 
an environment value, you must use putenv. 

On success, getenv returns the value associated with name. If the specified 
name is not defined in the environment, getenv returns a NULL pointer. 

_environ (global variable), getpsp, putenv 
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getfat 



getfat 

Function 
Syntax 



Remarks 



dos.h 



Return value 
See also 



Gets file allocation table information for given drive. 

void getfat (unsigned char drive, struct fatinfo *dtable); : 
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■ 




■ 











getfat gets information from the file allocation table (FAT) for the drive 
specified by drive (0 for default, 1 for A, 2 for B, and so on), dtable points to 
the fatinfo structure to be filled in. The fatinfo structure filled in by getfat is 
defined as follows: 



struct fatinfo { 

char fi_sclus; 

char fi_fatid; 

unsigned fi_nclus; 

int fi_bysec; 
}; 

None. 

getdfree, getfatd 



/* sectors. per cluster */ 

/* the FAT id byte */ 

/* number of clusters */ 

/* bytes per sector */ 



getfatd 



dos.h 



Function 
Syntax 



Remarks 



Gets file allocation table information. 

void getfatd (struct fatinfo *dtable); 
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■ 




■ 











getfatd gets information from the file allocation table (FAT) of the default 
drive, dtable points to the fatinfo structure to be filled in. 

The fatinfo structure filled in by getfatd is defined as follows: 





struct fatinfo { 




char fi_sclus; 




char fi_fatid; 




int fi_nclus; 




int fi_bysec; 

} ; 


Return value 


None. 



/* sectors per cluster */ 

/* the FAT id byte */ 

/* number of clusters */ 

/* bytes per sector *•/ 
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gettata 



See also 



getdfree, getfat 



getftime, setftime 



io.h 



Function 
Syntax 



Remarks 



Return value 



Gets and sets the file date and time. 

int getftime(int handle, struct ftime *ftimep); 
int setftime(int handle, struct ftime *ftimep); 



DOS 


UNIX 
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■ 




■ 


■ 






■ 




getftime retrieves the file time and date for the disk file associated with the 
open handle. The ftime structure pointed to by ftimep is filled in with the 
file's time and date. 

setftime sets the file date and time of the disk file associated with the open 
handle to the date and time in the ftime structure pointed to by ftimep. The 
file must not be written to after the setftime call or the changed information 
will be lost. The file must be open for writing; an EACCES error will occur 
if the file is open for read-only access. 

The ftime structure is defined as follows: 



struct ftime { 

unsigned ft_tsec: 5; 
. unsigned ft_min: 6; . 
unsigned ft_hour: 5; 
unsigned ft_day: 5; 
unsigned ft_month: 4; 
unsigned ft_year: 7; 
}; 



7* two seconds 
/* minutes */ 
/* hours */ 
/* days */ 
/* months */ 
/* year - 1980*/ 



/ 



getftime and setftime return on success. 

In the event of an error return, -1 is returned and the global variable errno 
is set to one of the following values: 



See also 



EACCES 

EBADF 

EINVFNC 

fflush, open 



Permission denied 
Bad file number 
Invalid function number 
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getpass 



getpass 

Function 
Syntax 



Remarks 



conio.h 



Return value 
See also 



Reads a password. 

char *getpass (const char *prompt); 
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■ 


■ 




■ 






■ 



getpass reads a password from the system console, after prompting with the 
null-terminated string prompt and disabling the echo. A pointer is returned 
to a null-terminated string of up to eight characters (not counting the null 
character). 

This function should not be used in Win32s or Win32 GUI applications. 

The return value is a pointer to a static string, which is overwritten with 
each call. 

getch 



getpid 



process.h 



Function 
Syntax 



Remarks 
Return value 

See also 

getpsp 



Gets the process ID of a program. 

unsigned getpid (void) . 
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OS/2 


* 


■ 


■ 


■ 






■ 



This function returns the current process ID — an integer that uniquely 
identifies the process. 

getpid returns the identification number of the current process. 

getpsp, _psp (global variable) 



dos.h 



Function 



Gets the program segment prefix (PSP). 
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getpsp 



Syntax 



Remarks 
Return value 
See also 



unsigned getpsp (void) ; 



gets 
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■ 




■ 











getpsp gets the segment address of the PSP using DOS call 0x62. 
getpsp returns the address of the PSP. 
getenv, jpsp (global variable) 



stdio.h 




Function 
Syntax 



Remarks 



Return value 
See also 



Gets a string from stdin. 

char *gets(char *s) ; 
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■ 




■ 


■ 


■ 


■ 



gets collects a string of characters terminated by a new line from the 
standard input stream stdin and puts it into s. The new line is replaced by a 
null character ('\0') in s. 

gets allows input strings to contain certain whitespace characters (spaces, 
tabs), gets returns when it encounters a new line; everything up to the new 
line is copied into s. 

For Win32s or Win32 GUI applications, stdin must be redirected. 

On success, gets returns the string argument s; it returns NULL on end-of- 
file or error. 

cgets, f error, fgets, fopen, fputs, fread, freopen, getc, puis, scanf 



gettext 



conio.h 



Function 



Copies text from text mode screen to memory. 
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gettext 



Syntax 



Remarks 



int gettext (int left, int top, int right, int bottom, void *destin) 



Return value 
See also 
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■ 






■ 






■ 



gettext stores the contents of an onscreen text rectangle defined by left, top, 
right, and bottom into the area of memory pointed to by destin. 

All coordinates are absolute screen coordinates, not window-relative. The 
upper left corner is (1,1). 

gettext reads the contents of the rectangle into memory sequentially from 
left to right and top to bottom. 

Each position onscreen takes 2 bytes of memory: The first byte is the 
character in the cell, and the second is the cell's video attribute. The space 
required for a rectangle w columns wide by h rows high is defined as 

bytes = (h rows) x (w columns) x 2 

This function should not be used in Win32s or Win32 GUI applications. 

gettext returns 1 if the operation succeeds. It returns if it fails (for example, 
if you gave coordinates outside the range of the current screen mode). 

movetext, puttext 



gettextinfo 



conio.h 



Function 
Syntax 



Remarks 



Gets text mode video information. 

void gettextinfo (struct text_info *r) ; 
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■ 






■ 






■ 



gettextinfo fills in the textjnfo structure pointed to by r with the current text 
video information. 

The textjnfo structure is defined in conio.h as follows: 



struct textjnfo { 

unsigned char winleft; 

unsigned char wintop; 

unsigned char winright;' 

unsigned char winbottom; 

unsigned char attribute; 



/* left windo-' coordinate */ 

/* top window coordinate.*/ 

/* right window coordinate */' 

/* bottom window coordinate */ 

/* text attribute */ 
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gettextinfo 



unsigned char normattr; 
unsigned char currmode; 
unsigned char screenheight; 
unsigned char screenwidth; 
unsigned char curx; 
unsigned char cury; 



/* normal attribute */ 

/* BW40, BW80.-C40, C80, or C43B0 */ 

/* text screen's height */ 

/* text screen's width */ 

/* x-coordinate in current window */ 

/* y-coordinate in current window */ 



Return value 
See also 



This function should not be used in Win32s or Win32 GUI applications. 

gettextinfo returns nothing; the results are returned in the structure pointed 
to by r. 

textattr, textbackground, textcolor, textmode, wherex, wherey, window 




gettime, settime 



dos.h 



Function 
Syntax 



gettime 
settime 



Remarks 



Return value 
See also 



Gets and sets the system time. 

void gettime (struct time *timep); 
void settime (struct time *timep); 
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■ 




■ 


■ 






■ 


■ 




■ 








■ 



gettime fills in the time structure pointed to by timep with the system's 
current time. 

settime sets the system time to the values in the time structure pointed to by 
timep. 

The time structure is defined as follows: 



struct time { 

unsigned char ti_min; 

unsigned char tijiour; 

unsigned char tijrnnd; 

unsigned char ti_sec; 
}; 



/* minutes */ 

/* hours */ 

/* hundredths of seconds */ 

/* seconds */ 



None. 

_dos_gettime, _dos_settime, getdate, setdate, stime, time 
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getvect, setvect 



getvect, setvect 



dos.h 



Function 
Syntax 



Remarks 



Return value 



See also 



Gets and sets interrupt vector. 



0; 



void interrupt (*getvect (int interruptno) 
void interrupt (*getvect( int interruptno)) ( . .. ); 
void setvect (int interruptno, void interrupt (*isr) 
void setvect (int interruptno, void interrupt (*isr) 



:)); 
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■ 




■ 











/* C version */ 
// C++ version 

/* C version */ 
// C++ version 



Every processor of the 8086 family includes a set of interrupt vectors, 
numbered to 255. The 4-byte value in each vector is actually an address, 
which is the location of an interrupt function. 

getvect reads the value of the interrupt vector given by interruptno and 
returns that value as a (far) pointer to an interrupt function. The value of 
interruptno can be from to 255. 

setvect sets the value of the interrupt vector named by interruptno to a new 
value, isr, which is a far pointer containing the address of a new interrupt 
function. The address of a C routine can be passed to isr only if that routine 
is declared to be an interrupt routine. 

In C++ only static member functions or non-member functions can be 
declared to be an interrupt routine. 

If you use the prototypes declared in dos.h, simply pass the address of an 
interrupt function to setvect in any memory model. 

getvect returns the current 4-byte value stored in the interrupt vector named 
by interruptno. 

setvect does not return a value. 

disable, _dos_getvect, _dos_setvect, enable, geninterrupt 



getverify 



dos.h 



Function 
Syntax 



Returns the state of the operating system verify flag. 

int getverify (void).; 
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■ 




■ 








-■ 



134 



Library Reference 



getverify 



Remarks 



Return value 
See also 



getw 



getverify gets the current state of the verify flag. 

The verify flag controls output to the disk. When verify is off, writes are not 
verified; when verify is on, all disk writes are verified to ensure proper 
writing of the data. 

getverify returns the current state of the verify flag, either (off) or 1 (on). 

setverify 

stdio.h 




Function 
Syntax 



Remarks 



Return value 



See also 



Gets integer from stream. 

int getw(FILE * stream) ; 
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■ 


■ 


■ 






■ 



getw returns the next integer in the named input stream. It assumes no 
special alignment in the file. 

getw should not be used when the stream is opened in text mode. 

getw returns the next integer on the input stream. On end-of-file or error, 
getw returns EOF. Because EOF is a legitimate value for getw to return, feof 
ovf error should be used to detect end-of-file or error. 

putw 



gmtime 



time.h 



Function 
Syntax 



Remarks 



Converts date and time to Greenwich mean time (GMT). 

struct tm *gmtime (const time_t *timer) ; 
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■ 


■ 


■ 



gmtime accepts the address of a value returned by time and returns a 
pointer to the structure of type tm containing the time elements, gmtime 
converts directly to GMT. 

The global long variable _timezone should be set to the difference in seconds 
between GMT and local standard time (in PST, _timezone is 8x60x60). The 
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gmtime 



global variable _daylight should be set to nonzero only if the standard U.S. 
daylight saving time conversion should be applied. 

This is the tm structure declaration from the time.h header file: 



Seconds */ 

Minutes */ 

Hour (0 - 23) */ 

Day of month (1 - 31) */ 

Month (0 - 11) */ 

Year (calendar year minus 1900) */ 

Weekday (0 - 6; Sunday is 0) */ 

Day of year (0 -365) */ 

Nonzero if daylight saving time is in effect. */ 



struct tm { 




int tm_sec; 


/ 


int tm_min; 


/ 


int tmjiour; 


/ 


int tmjmday; 


/ 


int tmjnon; 


/ 


int tm_year; 


/ 


int tm_wday; 


/ 


int tm_yday; 


/ 


int tm_isdst;. 


/ 



Return value 
See also 



These quantities give the time on a 24-hour clock, day of month (1 to 31), 
month (0 to 11), weekday (Sunday equals 0), year - 1900, day of year (0 to 
365), and a flag that is nonzero if daylight saving time is in effect. 

gmtime returns a pointer to the structure containing the time elements. This 
structure is a static that is overwritten with each call. 

asctime, ctime, ftime, localtime, stime, time, tzset 



gotoxy 



conio.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Positions cursor in text window. 

void gotoxyfint x, int y) ; 
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■ 






' 



gotoxy moves the cursor to the given position in the current text window. If 
the coordinates are in any way invalid, the call to gotoxy is ignored. An 
example of this is a call to gotoxy (40, 30), when (35,25) is the bottom right 
position in the window. 

Neither argument to gotoxy can be zero. 

This function should not be used in Win32s or Win32 GUI applications. 

None. 

wherex, wherey, window 
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Jieapadd 



heapadd 



Function 
Syntax 



Remarks 

Return value 
See also 



malloc.h 



Add a block to the heap. 

int Jieapadd (void ■♦block, size_t size); 
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■ 






■ 



This function adds a new block of memory to the heap. The block must not 
have been previously allocated from the heap. Jieapadd is typically used to 
add large static data areas to the heap. 

Jieapadd returns if it is successful, and -1 if it is unsuccessful. 

free, malloc 




heapcheck 



alloc.h 



Function 
Syntax 



Remarks 
Return value 



Checks and verifies the heap. 

int heapcheck (void) ; 
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■ 






■ 



heapcheck walks through the heap and examines each block, checking its 
pointers, size, and other critical attributes. 

The return value is less than for an error and greater than for success. 
The return values and their meaning are as follows: 

_HEAPCORRUPT Heap has been corrupted 
_HEAPEMPTY No heap 

_HEAPOK Heap is verified 



heapcheckfree 



alloc.h 



Function 
Syntax 



Checks the free blocks on the heap for a constant value. 

int heapcheckfree (unsigned int f il lvalue ); 
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heapcheckfree 



Return value 
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■ 






■ 






■ 



The return value is less then for an error and greater than for success. 
The return values and their meaning are as follows: 



_BAD VALUE A value other than the fill value was found 

_HEAPCORRUPT Heap has been corrupted 

_HEAPEMPTY No heap 

_HEAPOK Heap is accurate 



heapchecknode 



alloc.h 



Function 
Syntax 



Remarks 



Return value 



Checks and verifies a single node on the heap. 

int heapchecknode (void *node) ; 
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■ 






■ 






■ 



If a node has been freed and heapchecknode is called with a pointer to the 
freed block, heapchecknode can return _BADNODE rather than the expected 
_FREEENTRY. This is because adjacent free blocks on the heap are merged, 
and the block in question no longer exists. 

One of the following values: 



Jieapchk 



_BADNODE Node could not be found 

_FREEENTRY Node is a free block 

_HEAPCORRUPT Heap has been corrupted 

_HEAPEMPTY No heap 

USEDENTRY Node is a used block 



malloch 



Function 
Syntax 



Checks and verifies the heap. 

int _heapchk (void); 



DOS 


UNIX 


Win 16 


Win 32 
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■ 






■ 
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Jieapchk 



Remarks 
Return value 



Jieapchk walks through the heap and examines each block, checking its 
pointers, size, and other critical attributes. 

One of the following values: 



See also 



heapfillfree 



_HEAPBADNODE A corrupted heap block has been found 

_HEAPEMPTY No heap exists 

_HEAPOK The heap appears to be uncorrupted 

Jieapset, _rtl_heapwalk 



alloc.h 




Function 
Syntax 



Return value 



Fills the free blocks on the heap with a constant value. 

int heapfillfree (unsigned int fillvalue) ; 
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■ 






■ 



One of the following values: 



_HEAPCORRUPT Heap has been corrupted 

_HEAPEMPTY No heap 

_HE APOK Heap is accurate 



Jieapmin 



malloc.h 



Function 
Syntax 



Remarks 



Return value 



Release unused heap areas. 

int Jieapmin (void); 
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■ 


- 






■ 



The Jieapmin function returns unused areas of the heap to the operating 
system. This allows blocks that have been allocated and then freed to be 
used by other processes. Due to fragmentation of the heap, Jieapmin might 
not always be able to return unused memory to the operating system; this 
is not an error. 

Jieapmin returns if it is successful, or -1 if an error occurs. 
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Jieapmin 



See also 



free, malloc 



Jieapset 

Function 
Syntax 



Remarks 



malloc.h 



Return value 



Fills the free blocks on the heap with a constant value. 

int Jieapset (unsigned int fillvalue); 
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■ 






■ 



See also 



Jieapset checks the heap for consistency using the same methods as 
Jieapchk. It then fills each free block in the heap with the value contained in 
the least significant byte of fillvalue. This function can be used to find heap- 
related problems. It does not guarantee that subsequently allocated blocks 
will be filled with the specified value. 

One of the following values: 

_HEAPOK The heap appears to be uncorrupted 

_HEAPEMPTY No heap exists 

_HE APBADNODE A corrupted heap block has been found 

Jieapchk, jtljeapwalk 



heapwalk 



alloc.h 



Function 
Syntax 



Remarks 



heapwalk is used to "walk" through the heap, node by node. 

int heapwalk (struct heapinfo *hi); 
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■ 



heapwalk assumes the heap is correct. Use heapcheck to verify the heap before 
using heapwalk. _HEAPOK is returned with the last block on the heap. 
_HEAPEND will be returned on the next call to heapwalk. 

heapwalk receives a pointer to a structure of type heapinfo (declared in 
alloc.h). For the first call to heapwalk, set the hi.ptr field to null, heapwalk 
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heapwalk 



Return value 



returns with hi.ptr containing the address of the first block, hi.size holds 
the size of the block in bytes. hi.in_use is a flag that's set if the block is 
currently in use. 

One of the following values: 



See also 



heapwalk 



Remarks 



_HEAPEMPTY No heap 

_HEAPEND End of the heap has been reached 

_HEAPOK Heapinfo block contains valid data 

farheapwalk, _rtljieapwalk 



Obsolete nction. See _rtl_heapwalk. 



malloc.h 




highvideo 



conio.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Selects high-intensity characters. 

void highvideo (void) ; 
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■ 






■ 






■ 



highvideo selects high-intensity characters by setting the high-intensity bit of 
the currently selected foreground color. 

This function does not affect any characters currently onscreen, but does 
affect those displayed by functions (such as cprintf) that perform direct 
video, text mode output after highvideo is called. 

This function should not be used in Win32s or Win32 GUI applications. 

None. 

cprintf, cputs, gettextinfo, lowvideo, normvideo, textattr, textcolor 



hypot, hypotl 



math.h 



Function 



Calculates hypotenuse of a right triangle. 
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hypot, hypotl 



Syntax 



Remarks 



hypot 
hypotl 



Return value 



double hypot (double x, double y) ; 

long double hypotl (long double x, long double y) 
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■ 


■ 






■ 


■ 




■ 


■ 






■ 



hypot calculates the value z where 

z 2 = x 2 + y 2 and z >= 

This is equivalent to the length of the hypotenuse of a right triangle, if the 
lengths of the two sides are x and y. , 

hypotl is the long double version; it takes long double arguments and 
returns a long double result. 

On success, these functions return z, a double (hypot) or a long double) 
(hypotl): On error (such as an overflow), they set the global variable errno to 

ERANGE Result out of range 

and return the value HUGE_VAL (hypot) or _LHUGE_VAL (hypotl). Error 
handling for these routines can be modified through the functions jnatherr 
and matherrl. 



JnitEasyWin 



io.h 



Function 
Syntax 



Remarks 
Return value 



Initializes Easy Windows. 

void JnitEasyWin (void) ; 
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■ 











JnitEasyWin allows programs to use functions which perform console I/O 
within 16-bit Windows. , 

None. 



inp 



conio.h 



Function 
Syntax 



Reads a byte from a hardware port. 

int .inp (unsigned portid) ; 
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inp 



Remarks 



Return value 
See also 
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■ 




■ 











inp is a macro that reads a byte from the input port specified by portid. If inp 
is called when conio.h has been included, it will be treated as a macro that 
expands to inline code. If you don't include conio.h, or if you do include 
conio.h and undefine the macro inp, you get the inp function. 

inp returns the value read. 

inpw, outp, outpw 



inport 



dos.h 




Function 
Syntax 



Remarks 

Return value 
See also 



Reads a word from a hardware port. 

int inport (int portid); 
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■ 











inport works just like the 80x86 instruction IN. It reads the low byte of a 
word from the input port specified by portid; it reads the high byte from 
portid + 1. 

inport returns the value read. 

inportb, outport, outportb 



inportb 



dos.h 



Function 
Syntax 



Remarks 



Return value 



Reads a byte from a hardware port. 

unsigned char inportb(int portid); 
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■ 











inportb is a macro that reads a byte from the input port specified by portid. 

If inportb is called when dos.h has been included, it will be treated as a 
macro that expands to inline code. If you don't include dos.h, or if you do 
include dos.h and #undef the macro inportb, you get the inportb function. 

inportb returns the value read. 
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inportb 



See also 



inport, outport, outportb 



inpw 



conio.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Reads a word from a hardware port. 

unsigned inpw (unsigned portid) ; 
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■ 




■ 











inpw is a macro that reads a 16-bit word from the inport port specified by 
portid. It reads the low byte of the word from portid, and the high byte from 
portid + 1. 

If inpw is called when conio.h has been included, it will be treated as a 
macro that expands to inline code. If you don't include conio.h, or if you do 
include conio.h and #undef the macro inpw, you get the inpw function. 

inpw returns the value read. 

inp, outp, outpw 



insline 



conio.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Inserts a blank line in the text window. 

void insline (void) ; 
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■ 



insline inserts an empty line in the text window at the cursor position using 
the current text background color. All lines below the empty one move 
down one line, and the bottom line scrolls off the bottom of the window. 

This function should not be used in Win32s or Win32 GUI applications. 

None. 

clreol, delline, window 
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int86 



dos.h 



Function 
Syntax 



Remarks 



Return value 



General 8086 software interrupt. 

int int86(int intno, union REGS *inregs, union REGS *outregs) 
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■ 











See also 



int86 executes an 8086 software interrupt specified by the argument intno. 
Before executing the software interrupt, it copies register values from inregs 
into the registers. 

After the software interrupt returns, int86 copies the current register values 
to outregs, copies the status of the carry flag to the x.cflag field in outregs, 
and copies the value of the 8086 flags register to the x. flags field in outregs. If 
the carry flag is set, it usually indicates that an error has occurred. 

Note that inregs can point to the same structure that outregs points to. 

int86 returns the value of AX after completion of the software interrupt. If 
-the carry flag is set (outregs -> x. cf lag ! - 0), indicating an error, this 
function sets the global variable _doserrno to the error code. Note that when 
the carry flag is not set (outregs -> x.cflag = 0), you may or may not have 
an error. To be certain, always check _doserrno. 

bdos, bdosptr, geninterrupt, int86x, intdos, intdosx, intr 




int86x 



dos.h 



Function 
Syntax 



Remarks 



General 8086 software interrupt interface. 

int int86x(int intno, union REGS *inregs, union REGS *outregs, 
struct SREGS *segregs); 
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■ 











int86x executes an 8086 software interrupt specified by the argument intno. 
Before executing the software interrupt, it copies register values from inregs 
into the registers. 

In addition, int86x copies the segregs ->ds and segregs ->es values into the 
corresponding registers before executing the software interrupt. This 
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int86x 



Return value 



See also 



feature allows programs that use far pointers or a large data memory 
model to specify which segment is to be used for the software interrupt. 

After the software interrupt returns, int86x copies the current register 
values to outregs, the status of the carry flag to the x.cflag field in outregs, 
and the value of the 8086 flags register to the x.flags field in outregs. In 
addition, int86x restores DS and sets the segregs ->es and segregs ->ds fields 
to the values of the corresponding segment registers. If the carry flag is set, 
it usually indicates that an error has occurred. 

int86x lets you invoke an 8086 software interrupt that takes a value of DS 
different from the default data segment, and /or takes an argument in ES. 

Note that inregs can point to the same structure that outregs points to. 

int86x returns the value of AX after completion of the software interrupt. If 
the carry flag is set (outregs -> x. cf lag ! = 0), indicating an error, this 
function sets the global variable _doserrno to the error code. Note that when 
the carry flag is not set (outregs ->■ x. cf lag = 0), you may or may not have 
an error. To be certain, always check _doserrho. 

bdos, bdosptr, geninterrupt, intdos, intdosx, int86, intr, segread 



intdos 



dos.h 



Function 
Syntax 



Remarks 



Return value 



General DOS interrupt interface. 

int intdos (union REGS * inregs, union REGS *outregs) 
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■ 











intdos executes DOS interrupt 0x21 to invoke a specified DOS function. The 
value of inregs -> h.ah specifies the DOS function to be invoked. 

After the interrupt 0x21 returns, intdos copies the current register values to 
outregs, copies the status of the carry flag to the x.cflag field in outregs, and 
copies the value of the 8086 flags register to the x.flags field in outregs. If the 
carry flag is set, it indicates that an error has occurred. 

Note that inregs can point to the same structure that outregs points to. 

intdos returns the value of AX after completion of the DOS function call. If 
the carry flag is set (outregs -> x. cf lag ! = 0), indicating an error, it sets the 
global variable _doserrno to the error code. Note that when the carry flag is 
not set (outregs -> x. cf lag = 0), you may or may not have an error. To.be 
certain, always check _doserrno. 
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intdos 



See also 

intdosx 



bdos, bdosptr, geninterrupt, int86, int86x, intdosx, intr 



dos.h 



Function 
Syntax 



Remarks 



Return value 



General DOS interrupt interface. 

int intdosx (union REGS *inregs, union REGS *outregs, struct SREGS *segregs); 
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■ 











See also 



intdosx executes DOS interrupt 0x21 to invoke a specified DOS function. 
The value of inregs -> h.ah specifies the DOS function to be invoked. 

In addition, intdosx copies the segregs ->ds and segregs ->es values into the 
corresponding registers before invoking the DOS function. This feature 
allows programs that use far pointers or a large data memory model to 
specify which segment is to be used for the function execution. 

After the interrupt 0x21 returns, intdosx copies the current register values to 
outregs, copies the status of the carry flag to the x.cflag field in outregs, and 
copies the value of the 8086 flags register to the x.flags field in outregs. In 
addition, intdosx sets the segregs ->es and segregs ->ds fields to the values of 
the corresponding segment registers and then restores DS. If the carry flag 
is set, it indicates that an error occurred. 

intdosx lets you invoke a DOS function that takes a value of DS different 
from the default data segment and /or takes an argument in ES. 

Note that inregs can point to the same structure that outregs points to. 

intdosx returns the value of AX after completion of the DOS function call. If 
the carry flag is set (outregs -> x.cflag != 0), indicating an error, it sets the 
global variable _doserrno to the error code. Note that when the carry flag is 
not set (outregs -> x . cf lag = 0), you may or may not have an error. To be 
certain, always check _doserrno. 

bdos, bdosptr, geninterrupt, int86, int86x, intdos, intr, segread 




intr 



dos.h 



Function 
Syntax 



Alternate 8086 software interrupt interface. 

void 'intr (int intno, struct REGPACK *preg) ; 
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intr 



Remarks 
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■ 




■ 











The intr function is an alternate interface for executing software interrupts. 
It generates an 8086 software interrupt specified by the argument intno. 

intr copies register values from the REGPACK structure *preg into the 
registers before executing the software interrupt. After the software 
interrupt completes, intr copies the current register values into *preg, 
including the flags. 

The arguments passed to intr are as follows: 



Return value 
See also 



intno Interrupt number to be executed 
preg Address of a structure containing 

(a) the input registers before the interrupt call 

(b) the value of the registers after the interrupt call 

The REGPACK structure (defined in dos.h) has the following format: 

struct REGPACK { 

unsigned r_ax, r_bx, r_cx, r_dx; 

unsigned r_bp, r_si, r_di, r_ds, r_es, r_flags; 
}; 

No value is returned. The REGPACK structure *preg contains the value of 
the registers after the interrupt call. 

geninterrupt, int86, int86x, intdos, intdosx 



ioctl 



io.h 



Function 
Syntax 



Remarks 



Controls I/O device. 

int ioctl (int handle, int func' [, void *argdx, int argcx] ) ; 
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■ 











ioctl is available on UNIX systems, but not with these parameters or 
functionality. UNIX version 7 and System III differ from each other in their 
use of ioctl. ioctl calls are not portable to UNIX and are rarely portable 
across DOS machines. 

DOS 3.0 extends ioctl with func values of 8 and 11. 
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ioctl 



This is a direct interface to the DOS call 0x44 (IOCTL). 
The exact function depends on the value oifunc as follows: 

Get device information. 

1 Set device information (in argdx). 

2 Read argcx bytes into the address pointed to by argdx. 

3 Write argcx bytes from the address pointed to by argdx. 

4 Same as 2 except handle is treated as a drive number (0 equals 
default, 1 equals A, and so on). 

5 Same as 3 except handle is a drive number (0 equals default, 1 
equals A, and so on). 

6 Get input status. 

7 Get output status. 

8 Test removability; DOS 3.0 only. 

11 Set sharing conflict retry count; DOS 3.0 only. 

ioctl can be used to get information about device channels. Regular files can 
also be used, but only func values 0, 6, and 7 are defined for them. All other 
calls return an EINYAL error for files. 

See the documentation for system call 0x44 in your DOS reference manuals 
for detailed information on argument or return values. 

The arguments argdx and argcx are optional. 

ioctl provides a direct interface to DOS device drivers for special functions. 
As a result, the exact behavior of this function varies across different 
vendors' hardware and in different devices. Also, several vendors do not 
follow the interfaces described here. Refer to the vendor BIOS 
documentation for exact use of ioctl. 

Return value For func or 1, the return value is the device information (DX of the ioctl 

call). For func values of 2 through 5, the return value is the number of bytes 
actually transferred. For func values of 6 or 7, the return value is the device 
status. 

In any event, if an error is detected, a value of -1 is returned, and the global 
variable errno is set to one of the following: 

EBADF Bad file number 

EINVAL Invalid argument 
EINVDAT Invalid data 




Chapter 3, Run-time functions 149 



isalnum 



isalnum 

Function 
Syntax 



Remarks 



Return value 



ctype.h 



Tests for an alphanumeric character. 

int isalnum (int c) ; 
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■ 


■ 


■ 


■ 


■ 


■ 



isalnum is a macro that classifies ASCII-coded integer values by table 
lookup. The macro is affected by the current locale's LC_CTYPE category. 
For the default C locale, c is a letter (A to Z or a to z) or a digit (0 to 9). 

You can make this macro available as a function by undefining (#undef) it. 

It is a predicate returning nonzero for true and for false, isalnum returns 
nonzero if c is a letter or a digit. 



isalpha 



ctype.h 



Function 
Syntax 



Remarks 



Return value 



Classifies an alphabetical character. 

int isalpha (int c) ; 
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isalpha is a macro that classifies ASCII-coded integer values by table lookup. 
The macro is affected by the current locale's LC_CTYPE category. For the 
default C locale, c is a letter (A to Z or a to z). 

You can make this macro available as a function by undefining (#undef) it. 

isalpha returns nonzero if c is a letter. 



isascii 



ctype.h 



Function 
Syntax 



Character classification macro. 

int isascii (int c) ; 
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■ 
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■ 
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isascn 



Remarks 



Return value 



isascii is a macro that classifies ASCII-coded integer values by table lookup. 
It is a predicate returning nonzero for true and for false. 

isascii is defined on all integer values. 

isascii returns nonzero if the low order byte of c is in the range to 127 
(0x00-0x7F). 



isatty 



io.h 



Function 
Syntax 



Remarks 



Return value 



Checks for device type. 

int isatty (int handle); 
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■ 






■ 




isatty determines whether handle is associated with any one of the following 
character devices: 

■ A terminal 

■ A console 

■ A printer 

■ A serial port 

If the device is one of the four character devices listed above, isatty returns 
a nonzero integer. If it is not such a device, isatty returns 0. 



iscntrl 



ctype.h 



Function 
Syntax 



Remarks 



Tests for a control character. 

int iscntrl (int c) ; 
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iscntrl is a macro that classifies ASCII-coded integer values by table lookup. 
The macro is affected by the current locale's LC_CTYPE category. For the 
default C locale, c is a delete character or control character (0x7F or 0x00 to 
OxlF). 

You can make this macro available as a function by undefining (#undef) it. 
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iscntrl 



Return value iscntrl returns nonzero if c is a delete character or ordinary control 

character. 



isdigit 



ctype.h 



Function 
Syntax 



Remarks 



Return value 



Tests for decimal-digit character. 

int isdigit (int c) ; 
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isdigit is a macro that classifies ASCII-coded integer values by table lookup. 
The macro is affected by the current locale's LC_CTYPE category. For the 
default C locale, c is a digit (0 to 9). 

You can make this macro available as a function by undefining (#undef) it. 

isdigit returns nonzero if c is a digit. 



isgraph 



ctype.h 



Function 
Syntax 



Remarks 



Return value 



Tests for printing character. 

int isgraph (int c) ; 
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isgraph is a macro that classifies ASCII-coded integer values by table 
lookup. The macro is affected by the current locale's LC_CTYPE category. 
For the default C locale, c is a printing character except blank space (' '). 

You can make this macro available as a function by undefining (#undef) it. 

isgraph returns nonzero if c is a printing character. 



islower 



ctype.h 



Function 
Syntax 



Tests for lowercase character. 

int islower (int c) ; 
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islower 



Remarks 



Return value 
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islower is a macro that classifies ASCII-coded integer values by table 
lookup. The macro is affected by the current locale's LC_CTYPE category. 
For the default C locale, c is a lowercase letter (a to z). 

You can make this macro available as a function by undefining (#undef) it. 

islower returns nonzero if c is a lowercase letter. 



isprint 



ctype.h 




Function 
Syntax 



Remarks 



Return value 



Tests for printing character. 

int isprint (int c) ; 
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isprint is a macro that classifies ASCII-coded integer values by table lookup. 
The macro is affected by the current locale's LC_CTYPE category. For the 
default C locale, c is a printing character including the blank space (' '). 

You can make this macro available as a function by undefining (#undef) it. 

isprint returns nonzero if c is a printing character. 



ispunct 



ctype.h 



Function 
Syntax 



Remarks 



Return value 



Tests for punctuation character. 

int ispunct (int c) ; 
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ispunct is a macro that classifies ASCII-coded integer values by table 
lookup. The macro is affected by the current locale's LC_CTYPE category. 
For the default C locale, c is any printing character that is neither an alpha- 
numeric nor a blank space (' '). 

You can make this macro available as a function by undefining (#undef) it. 

ispunct returns nonzero if c is a punctuation character. 
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isspace 



isspace 

Function 
Syntax 



Remarks 



Return value 



ctype.h 



Tests for space character. 

int isspace (int c) ; , 
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isspace is a macro that classifies ASCII-coded integer values by table lookup. 
The macro is affected by the current locale's LC_CTYPE category. 

You can make this macro available as a function by undefining (#undef) it. 

isspace returns nonzero if c is a space, tab, carriage return, new line, vertical 
tab, formfeed (0x09 to OxOD, 0x20), or any other locale-defined space 
character. 



isupper 



ctype.h 



Function 
Syntax 



Remarks 



Return value 



Tests for uppercase character. 

int isupper (int c) ; 
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isupper is a macro that classifies ASCII-coded integer values by table 
lookup. The macro is affected by the current locale's LC_CTYPE category. 
For the default C locale, c is an uppercase letter (A to Z). 

You can make this macro available as a function by undefining (#undef) it. 

isupper returns nonzero if c is an uppercase letter. 



isxdigit 



ctype.h 



Function 
Syntax 



Tests for hexadecimal character. 

int isxdigit (int c) ; 
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isxdigit 



Remarks 



Return value 



isxdigit is a macro that classifies ASCII-coded integer values by table 
lookup. The macro is affected by the current locale's LC_CTYPE category. 

You can make this macro available as a function by undefining (#undef) it. 

isxdigit returns nonzero if c is a hexadecimal digit (0 to 9, A to F, a to f) or 
any other hexadecimal digit defined by the locale. 



itoa 



stdlib.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Converts an integer to a string. 

char *itoa(int value, char *string, int radix); 
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itoa converts value to a null-terminated string and stores the result in string. 
With itoa, value is an integer. 

radix specifies the base to be used in converting value; it must be between 2 
and 36, inclusive. If value is negative and radix is 10, the first character of 
string is the minus sign (-). 

The space allocated for string must be large enough to hold the returned 
string, including the terminating null character (\0). itoa can return up to 17 
bytes. 

itoa returns a pointer to string. 

Itoa, ultoa 



kbhit 



conio.h 



Function 
Syntax 



Checks for currently available keystrokes. 

int kbhit (void) ; 
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kbhit 



Remarks 

Return value 
See also 



kbhit checks to see if a keystroke is currently available. Any available 
keystrokes can be retrieved with getch or getche. 

This function should not be used in Win32s or Win32 GUI applications. 

If a keystroke is available, kbhit returns a nonzero value. Otherwise, it 
returns 0. 

getch, getche 



labs 



math.h 



Function 
Syntax 



Remarks 
Return value 
See also 



Gives long absolute value. 

long labs (long int x) ; 
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labs computes the absolute value of the parameter x. 
labs returns the absolute value of x. 
abs, cabs, jabs 



Idexp, Idexpl 



math.h 



Function 
Syntax 



Idexp 
Idexpl 



Remarks 



Return value 



See also 



Calculates x x 2 ex P. 

double Idexp (double x, int exp); 

long double Idexpl (long double x, int exp); 
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Idexp calculates the double value x x 2 ex P. 

expl is the long double version; it takes a long double argument for x and 
returns a long double result. 

On success, Idexp (or Idexpl) returns the value it calculated, x x 2 ex P. Error 
handling for these routines can be modified through the functions jnatherr 
and jnatherrl. 

exp, frexp, modf 
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Idiv 



Idiv 

Function 
Syntax 



Remarks 



Return value 
See also 



stdlib.h 



Divides two longs, returning quotient and remainder. 

ldiv_t ldivflong int numer, long int denom) ; 
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Idiv divides two longs and returns both the quotient and the remainder as 
an Idivjt type, numer and denom are the numerator and denominator, 
respectively. The Idivjt type is a structure of longs defined in stdlib.h as 
follows: 



typedef struct { 
long int quot; 
long int rem; 
} ldiv_t; 



/* quotient */ 
/* remainder */ 




Idiv returns a structure whose elements are quot (the quotient) and rem (the 
remainder). 

div 



Ifind 



stdlib.h 



Function 
Syntax 



Remarks 



Return value 



Performs a linear search. 

void *lfind (const void *key, const void *base, size_t *num, size_t width, 
int LUSERENTRY *fcmp) (const void *, const void *)); 
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Ifind makes a linear search for the value of key in an array , of sequential 
records. It uses a user-defined comparison routine fcmp. The fcmp function 
must be used with the _USERENTRY calling convention. 

The array is described as having *num records that are width bytes wide, 
and begins at the memory location pointed to by base. 

Ifind returns the address of the first entry in the table that matches the 
search key. If no match is found, Ifind returns NULL. The comparison 
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Ifind 



See also 



routine must return if *eleml == *elem2, and nonzero otherwise (eleml and 
eleml are its two parameters). 

bsearch, Isearch, qsort 



localeconv 



locale.h 



Function 
Syntax 



Remarks 



Queries the locale for numeric format. 

struct lconv *localeconv(void) ; 
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This function provides information about the monetary and other numeric 
formats for the current locale. The information is stored in a struct lconv 
type. The structure can only be modified by the setlocale. Subsequent calls to 
localeconv will update the lconv structure. 

The lconv structure is defined in locale.h. It contains the following fields: 



Table 3.1 : Locale monetary and numeric settings 



Field 



Application 



char *decimai_point, 
char *thousands_sep; 

char 'grouping; 

char *int_curr_symbol; 

char *currency_symbol; 
char *mon_decimal_point; 
char *mon_thousands_sep; 
char *mon_grouping; 
char *positive_sign; 
char *negative_sign; 
char int_frac_digits; 



Decimal point used in nonmonetary formats. This can never be an empty string. 

Separator used to group digits to the left of the decimal point. Not used with monetary 
quantities. 

Size of each group of digits. Not used with monetary quantities. See the value listing table 
below. 

International monetary symbol in the current locale. The symbol format is specified in the ISO 
4217 Codes for the Representation of Currency and Funds. 

Local monetary symbol for the current locale. 

Decimal point used to format monetary quantities. 

Separator used to group digits to the left of the decimal point for monetary quantities. 

Size of each group of digits used in monetary quantities. See the value listing table below. 

String indicating nonnegative monetary quantities. 

String indicating negative monetary quantities. 

Number of digits after the decimal point that are to be displayed in an internationally formatted 
monetary quantity. 
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localeconv 



Table 3.1: Locale monetary and numeric settings (continued) 



char frac_digits; 

char p_cs_precedes; 

char p_sep_by_space; 

char n_cs_precedes; 

char n_sep_by_space; 

char p_sign_posn; 
char n_sign_posn; 



Number of digits after the decimal point that are to be displayed in a formatted monetary 
quantity. 

Set to 1 if currency_symbol precedes a nonnegative formatted monetary quantity. If 
currency_symbol is after the quantity, it is set to 0. 

Set to 1 if currency_symbol\s to be separated from the nonnegative formatted monetary 
quantity by a space. Set to if there is no space separation. 

Set to 1 if currency_symbol precedes a negative formatted monetary quantity. If 
currency_symbol is after the quantity, set to 0. 

Set to 1 if currency_symbol is to be separated from the negative formatted monetary quantity 
by a space. Set to if there is no space separation. 

Indicate where to position the positive sign in a nonnegative formatted monetary quantity. 

Indicate where to position the positive sign in a negative formatted monetary quantity. 



Any of the above strings (except decimal _point) that is empty "" is not 
supported in the current locale. The nonstring char elements are nonnega- 
tive numbers. Any nonstring char element that is set to CHAR_MAX 
indicates that the element is not supported in the current locale. 

The grouping and mon_grouping elements are set and interpreted as follows: 



Value 



Meaning 



CHAR_MAX 


any other integer 



No further grouping is to be performed. 

The previous element is to be used repeatedly for the remainder 
of the digits. 

Indicates how many digits make up the current group. The next 
element is read to determine the size of the next group of digits 
before the current group. 



The p_sign_posn and n_sign_posn elements are set and interpreted as 
follows: 



Value 



Meaning 



Use parentheses to surround the quantity and currency_symbol 
Sign string precedes the quantity and currency_symbol. 
Sign string succeeds the quantity and currency_symbol. 
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localeconv 



Value 

3 

4 



Meaning 

Sign string immediately precedes the quantity and 
currency_symbol. 

Sign string immediately succeeds the quantity and 
currency_symbol. - 



Return value 



See also 



Returns a pointer to the filled-in structure of type struct Iconv. The values in 
the structure will change whenever setlocale modifies the LC_MONETARY 
or LC_NUMERIC categories. 

setlocale 



localtime 



time.h 



Function 
Syntax 



Remarks 



Converts date and time to a structure. 

struct tm *localtime (const time_t *timer); 
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localtime accepts the address of a value returned by time and returns a 
pointer to the structure of type tm containing the time elements. It corrects 
for the time zone and possible daylight saving time. 

The global long variable timezone contains the difference in seconds be- 
tween GMT and local standard time (in PST, timezone is 8x60x60). The 
global variable daylight contains nonzero only if the standard U.S. daylight 
saving time conversion should be applied. These values are set by tzset, not 
by the user program directly. 

This is the tm structure declaration from the time.h header file: 

struct tm { 
int tm_sec; 
int tm_min; 
int tm_hour; 
int tm_mday; 

int tmjnon; ■ 

int tm_year; 
int tm_wday; ' 
int tm_yday; 
int tm_isdst; 

}; 
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localtime 



Return value 
See also 



These quantities give the time on a 24-hour clock, day of month (1 to 31), 
month (0 to 11), weekday (Sunday equals 0), year - 1900, day of year (0 to 
365), and a flag that is nonzero if daylight saving time is in effect. 

localtime returns a pointer to the structure containing the time elements. 
This structure is a static that is overwritten with each call. 

asctime, ctime, ftime, gmtime, stime, time, tzset 



lock 



io.h 



Function 
Syntax 



Remarks 



Return value 



See also 



Sets file-sharing locks. 

int lock(int handle, long offset, long length); 
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lock provides an interface to the operating system file-sharing mechanism. 

A lock can be placed on arbitrary, nonoverlapping regions of any file. A 
program attempting to read or write into a locked region will retry the 
operation three times. If all three retries fail, the call fails with an error. 

lock returns on success. On error, lock returns -1 and sets the global 
variable errno to 

EACCES Locking violation 

locking, open, sopen, unlock 




locking 



io.h, sysMocking.h 



Function 
Syntax 



Remarks 



Sets or resets file-sharing locks. 

int locking (int handle, int cmd, long length); 
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locking provides an interface to the operating system file-sharing 
mechanism. The file to be locked or unlocked is the open file specified by 
handle. The region to be locked or unlocked starts at the current file 
position, and is length bytes long. 
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locking 



Locks can be placed on arbitrary, nonoverlapping regions of any file. A 
program attempting to read or write into a locked region will retry the 
operation three times. If all three retries fail, the call fails with an error. 

The cmd specifies the action to be taken (the values are defined in 
sysMocking.h): 

LKJLOCK Lock the region. If the lock is unsuccessful, try once a 

second for 10 seconds before giving up. 

LK.RLCK Same as LKJLOCK. 

LK_NBLCK Lock the region. If the lock if unsuccessful, give up 
immediately. 

LK_NBRLCK Same as LK.NBLCK. 

LKJJNLCK Unlock the region, which must have been previously 
locked. 

Return value On successful operations, locking returns 0. Otherwise, it returns -1, and the 

global variable errno is set to one of the following values: 



See also 



EACCES File already locked or unlocked 

EBADF Bad file number 

EDEADLOCK File cannot be locked after 10 retries (cmd is LKJLOCK 

orLK_RLCK) 
EINVAL Invalid cmd, or SHARE.EXE not loaded 

Jsopen, lock, open, sopen, unlock 



log, logl 



math.h 



Function 
Syntax 



Remarks 



log 
logl 



Calculates the natural logarithm of x. 

double log (double x) ; 

long double logl (long double x) ; 
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log calculates the natural logarithm of x. 

logl is the long double version; it takes a long double argument and returns 
a long double result. 
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log, logl 



Return value 



See also 



This function can be used with bed and complex types. 

On success, log and logl return the value calculated, ln(x). 

If the argument x passed to these functions is real and less than 0, the 
global variable errno is set to 

EDOM Domain error 

If x is 0, the functions return the value negative HUGEJVAL (log) or 
negative _LHUGE_VAL (logl), and set errno to ERANGE. Error handling for 
these routines can be modified through the functions jnatherr and 
jnatherrl. 

bed, complex, exp, loglO, sqrt 



Iog10, Iog10l 



math.h 




Function 
Syntax 



Remarks 



Return value 



See also 



Calculates log io(*)- 

double loglO (double x) ; 

long double loglOldong double x) 
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loglO calculates the base 10 logarithm of x. 

loglOl is the long double version; it takes a long double argument and 
returns a long double result. 

This function can be used with bed and complex types. 

On success, loglO (or loglOl) returns the value calculated, log 10 (x). 

If the argument x passed to these functions is real and less than 0, the 
global variable errno is set to 

EDOM Domain error 

If x is 0, these functions return the value negative HUGEJVAL (loglO) or 
_LHUGE_VAL (loglOl). Error handling for these routines can be modified 
through the functions jnatherr and jnatherrl. 

bed, complex, exp, log 
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longjmp 



longjmp 

Function 
Syntax 



Remarks 



setjmp.h 



Performs nonlocal goto. 

void longjmp (jmp_buf jmpb, int retval); 
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A call to longjmp restores the task state captured by the last call to setjmp 
with the argument jmpb. It then returns in such a way that setjmp appears to 
have returned with the value retval. 

A task state includes: 



Win 16 



Win 32 



Return value 
See also 



All segment registers 
CS, DS, ES, SS 

Register variables 
Dl and SI 

Stack pointer SP 

Frame pointer BP 

Flags 



No segment registers 
are saved 

Register variables 
EBX, EDI, ESI 

Stack pointer ESP 

Frame pointer EBP 

Flags are not saved 



A task state is complete enough that setjmp and longjmp can be used to 
implement co-routines. 

setjmp must be called before longjmp. The routine that called setjmp and set 
up jmpb must still be active and cannot have returned before the longjmp is 
called. If this happens, the results are unpredictable. 

longjmp cannot pass the value 0; if is passed in retval, longjmp will 
substitute 1. 

You can not use longjmp to switch between different threads in a 
multithread process. That is, do not jump to a jmpjbuf that was saved by a 
setjmp call in a different thread. 

None. 

ctrlbrk, setjmp, signal 
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lowvideo 



lowvideo 

Function 
Syntax 



Remarks 



conio.h 



Return value 
See also 



Selects low-intensity characters. 

void lowvideo (void) ; 
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lowvideo selects low-intensity characters by clearing the high-intensity bit of 
the currently selected foreground color. 

This function does not affect any characters currently onscreen. It affects 
only those characters displayed by functions that perform text mode, direct 
console output after this function is called. 

This function should not be used in Win32s or Win32 GUI applications. 

None. 

highvideo, normvideo, textattr, textcolor 




Irotl, Irotr 



stdlib.h 



Function 
Syntax 



Remarks 
Return value 

See also 



Rotates an unsigned long integer value to the left or right. 

unsigned long _lrotl (unsigned long val, int count); 
unsigned long _lrotr (unsigned long val, int count); 
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Jrotl rotates the given val to the left count bits. Jrotr rotates the given val to 
the right count bits. 

The functions return the rotated integer: 

■ Jrotl returns the value of val left-rotated count bits. 

■ Jrotr returns the value of val right-rotated count bits. 

_crotr, _crotl, jotl, jotr 



Chapter 3, Run-time functions 



165 



Isearch 



Isearch 

Function 
Syntax 



stdlib.h 



Remarks 



Return value 



Performs a linear search. 

void *lsearch(const void *key, void *base, size_t *num, size_t width, 
int (JJSERENTRY *fcmp) (const void *, const void *)); 
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See also 



Isearch searches a table for information. Because this is a linear search, the 
table entries do hot need to be sorted before a call to Isearch. If the item that 
key points to is not in the table, Isearch appends that item to the table. 

■ base points to the base (Oth element) of the search table. 

■ num. points to an integer containing the number of entries in the table. 

■ width contains the number of bytes in each entry. 

■ key points to the item to be searched for (the search key). 

The function fcmp must be used with the _USERENTRY calling convention. 

The argument fcmp points to a user-written comparison routine, that 
compares two items and returns a value based on the comparison. 

To search the table, Isearch makes repeated calls to the routine whose 
address is passed in fcmp. 

On each call to the comparison routine, Isearch passes two arguments: key, a 
pointer to the item being searched for, and elem, a pointer to the element of 
base being compared. 

fcmp is free to interpret the search key and the table entries in any way. 

Isearch returns the address of the first entry in the table that matches the 
search key. 

If the search key is not identical to *elem, fcmp returns a nonzero integer. If 
the search key is identical to *elem, fcmp returns 0. 

bsearch, Ifind, qsort 



Iseek 



io.h 



Function 
Syntax 



Moves file pointer. 

long lseek(int handle, long offset, int fromwhere); 
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Remarks 



Iseek 
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Iseek sets the file pointer associated with handle to a new position offset bytes 
beyond the file location given by fromwhere. fromwhere must be one of the 
following symbolic constants (defined in io.h): 



fromwhere 



File location 



SEEK_CUR Current file pointer position 

SEEK_END End-of-file 

SEEK_SET File beginning 



Return value 



See also 



Iseek returns the offset of the pointer's new position measured in bytes from 
the file beginning. Iseek returns -1L on error, and the global variable errno is 
set to one of the following values: 

EBADF Bad file handle 

EINVAL Invalid argument 
ESPIPE Illegal seek on device 

On devices incapable of seeking (such as terminals and printers), the return 
value is undefined. ^ 

filelength, fseek, ftell, getc, open, sopen, ungetc, _rtl_write, write 
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Itoa 



stdlib.h 



Function 
Syntax 



Remarks 



Converts a long to a string. 

char * Itoa (long value, char *string, int radix); 
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Itoa converts value to a null-terminated string and stores the result in string, 
value is a long integer. 

radix specifies the base to be used in converting value; it must be between 2 
and 36, inclusive. If value is negative and radix is 10, the first character of 
string is the minus sign (-). 
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Itoa 



Return value 
See also 



The space allocated for string must be large enough to hold the returned 
string, including the terminating null character (\0). Itoa can return up to 33 
bytes. 

Itoa returns a pointer to string. 

itoa, ultoa 



makepath 



stdlib.h 



Function 
Syntax 



Remarks 



Builds a path from component parts. 

void _makepath(char *path, const char *drive, const char *dir, 
const char *name, const char *ext); 
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jnakepath makes a path name from its components. The new path name is 

X:\DIR\SUBDIR\NAME.EXT 

where 



drive 


= 


X: 


dir 


= 


\DIR\SUBDIR\ 


name 


= 


NAME 


ext 


= 


.EXT 



Return value 



If drive is empty or NULL, no drive is inserted in the path name. If it is 
missing a trailing colon (:), a colon is inserted in the path name. 

If dir is empty or NULL, no directory is inserted in the path name. If it is 
missing a trailing slash (\ or /)> a backslash is inserted in the path name. 

If name is empty or NULL, no file name is inserted in the path name. 

If ext is empty or NULL, no extension is inserted in the path name. If it is 
missing a leading period (.), a period is inserted in the path name. 

jnakepath assumes there is enough space in path for the constructed path 
name. The maximum constructed length is _MAX_PATH. _MAX_PATH is 
defined in stdlib.h. 

jnakepath and _splitpath are invertible; if you split a given path with 
_splitpath, then merge the resultant components with jnakepath, you end up 
with path. 

None. 
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jnakepath 



See also 



Jullpath, _splitpath 



malloc 



stdlib.h 



Function 
Syntax 



Remarks 




Return value 



See also 



Allocates main memory. 

void *malloc(size_t size); 
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malloc allocates a block of size bytes from the memory heap. It allows a 
program to allocate memory explicitly as it's needed, and in the exact 
amounts needed. 

The heap is used for dynamic allocation of variable-sized blocks of 
memory. Many data structures, for example, trees and lists, naturally 
employ heap memory allocation. 

All the space between the end of the data segment and the top of the 
program stack is available for use in the small data models, except for a 
small margin immediately before the top of the stack. This margin is 
intended to allow the application some room to make the stack larger, in 
addition to a small amount needed by DOS. 

In the large data models, all the space beyond the program stack to the end 
of available memory is available for the heap. 

On success, malloc returns a pointer to the newly allocated block of 
memory. If not enough space exists for the new block, it returns NULL. The 
contents of the block are left unchanged. If the argument size == 0, malloc 
returns NULL. 

calloc, farcalloc, farmalloc, free, realloc 




matherr, matherrl 



'j _j 



math.h 



Function 
Syntax 



User-modifiable math error handler. 

int _matherr( struct _exception *e); 
int _matherrl (struct _exceptionl *e); 
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jnatherr, jnatherrl 



Remarks jnatherr is called when an error is generated by the math library. 

jnatherrl is the long double version; it is called when an error is generated 
by the long double math functions. 

jnatherr and jnatherrl each serve as a user hook (a function that can be 
customized by the user) that you can replace by writing your own math 
error handling routine. The example shows a user-defined jnatherr 
implementation. 

jnatherr and jnatherrl are useful for trapping domain and range errors 
caused by the math functions. They do not trap floating-point exceptions, 
such as division by zero. See signal for information on trapping such errors. 

You can define your own jnatherr or jnatherrl routine to be a custom error 
handler (such as one that catches and resolves certain types of errors); this 
customized function overrides the default version in the C library. The 
customized jnatherr or jnatherrl should return if it fails to resolve the 
error, or nonzero if the error is resolved. If nonzero is returned, no error 
message is printed and the global variable errno is not changed. 

Here are the _exception and _exceptionl structures (defined in math.h): 

struct _exception { 
.int type; 

char *name; 

double argl, arg2, retval; 
}; v 

struct _exceptionl { 
int type; 
char " *name; 
long double argl, arg2, retval; 

The members of the _exception and _exceptionl structures are shown in the 
following table: 

Member What it is (or represents) 

type The type of mathematical error that occurred; an enum type defined in the typedef 

_mexcep (see definition after this list). 

name A pointer to a null-terminated string holding the name of the math library function 

that resulted in an error. 

argl, The arguments (passed to the function that name points to) caused the error; 

arg2 if only one argument was passed to the function, it is stored in argl 

retval The default return value for _matherr (or _matherrl); you can modify this value. 
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The typedef jnexcep, also defined in math.h, enumerates the following 
symbolic constants representing possible mathematical errors: 



Symbolic 
constant 



Mathematical error 



DOMAIN Argument was not in domain of function, such as /og(-1 ). 

SING Argument would result in a singularity, such as pow(Q, -2). 

OVERFLOW Argument would produce a function result greater than DBL_MAX (or 

LDBL.MAX), such as exp(1000). 

UNDERFLOW Argument would produce a function result less than DBL_MIN (or 

LDBL_MIN),suchasexp(-1000). 

TLOSS Argument would produce function result with total loss of significant digits, 

suchass/n(10e70). 

The macros DBL_MAX, DBL_MIN, LDBL_MAX, and LDBL_MIN are 
defined in float.h. 

The source code to the default jnatherr and jnatherrl is on the Borland C++ 
distribution disks. 

The UNIX-style jnatherr and jnatherrl default behavior (printing a 
message and terminating) is not ANSI compatible. If you want a UNIX- 
style version of these routines, use MATHERR.C and MATHERRL.C ' 
provided on the Borland C++ distribution disks. 

Return value The default return value for jnatherr and jnatherrl is 1 if the error is 

UNDERFLOW or TLOSS, otherwise, jnatherr and jnatherrl can also 
modify e -> retval, which propagates back to the original caller. 

When jnatherr and jnatherrl return (indicating that they were not able to 
resolve the error), the global variable errno is set to and an error message 
is printed. 

When jnatherr and jnatherrl return nonzero (indicating that they were able 
to resolve the error), the global variable errno is not set and no messages are 
printed. 




max 



stdlib.h 



Function 
Syntax 



Returns the larger of two values. 

(type) max (a, b) ; 

template <class T> T max( T tl, T t2 
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max 



Remarks 

Return value 
See also 
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The C macro and the C++ template function compare two values and 
return the larger of the two. Both arguments and the routine declaration 
must be of the same type. 

max returns the larger of two values. 

min 



mblen 



stdlib.h 



Function 
Syntax 



Remarks 



Return value 



See also 



Determines the length of a multibyte character. 

int mblen(const char *s, size_t n) ; 
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If s is not null, mblen determines the number of bytes in the multibyte char- 
acter pointed to by s. The maximum number of bytes examined is specified 
by n. 

The behavior of mblen is affected by the setting of LC_CTYPE category of 
the current locale. 

If s is null, mblen returns a nonzero value if multibyte characters have 
state-dependent encodings. Otherwise, mblen returns 0. 

If s is not null, mblen returns if s points to the null character, and -1 if the 
next n bytes do not comprise a valid multibyte character; the number of 
bytes that comprise a valid multibyte character. 

mbstowcs, mbtowc, setlocale 



mbstowcs 



stdlib.h 



Function 
Syntax 



Converts a multibyte string to a wcharjt array. 

size_t mbstowcs (wchar_t *pwcs, const char *s, size_t n) ; 
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mbstowcs 



Remarks 



Return value 



See also 



The function converts the multibyte string s into the array pointed to by 
pwcs. No more than n values are stored in the array. If an invalid multibyte 
sequence is encountered, mbstowcs returns (sizej) -1. 

The pwcs array will not be terminated with a zero value if mbstowcs 
returns n. 

The behavior of mbstowcs is affected by the setting of LC_CTYPE category 
of the current locale. 

If an invalid multibyte sequence is encountered, mbstowcs returns (sizej) 
-1. Otherwise, the function returns the number of array elements modified, 
not including the terminating code, if any. 

mblen, mbtowc, setlocale 



mbtowc 



stdlib.h 




Function 
Syntax 



Remarks 



Return value 



See also 



Converts a multibyte character to wcharj code. 

int mbtowc (wchar_t *pwc, const char *s, size_t n) ; 
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If s is not null, mbtowc determines the number of bytes that comprise the 
multibyte character pointed to by s. Next, mbtowc determines the value of 
the type wcharj that corresponds to that multibyte character. If there is a 
successful match between wcharj and the multibyte character, and pwc is 
not null, the wcharj value is stored in the array pointed to by pwc. At most 
n characters are examined. 

When s points to an invalid multibyte character, -1 is returned. When s 
points to the null character, is returned. Otherwise, mbtowc returns the 
number of bytes that comprise the converted multibyte character. 

The return value never exceeds MB_CUR_MAX or the value of n. 

The behavior of mbtowc is affected by the setting of LC_CTYPE category of 
the current locale. 

mblen, mbstowcs, setlocale 
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memccpy, Jmemccpy 



memccpy, Jmemccpy 



mem.h 



Function 
Syntax 



memccpy 
Jmemccpy 



Remarks 



Return value 



See also 



Copies a block of n bytes. 

void *memccpy(void *dest, const void *src, int c, size_t n) ; 

void far* far _finemccpy(void far *dest, const void far *src, int c, size_t n) 
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memccpy is available on UNIX System V systems. 

memccpy copies a block of n bytes from src to dest . The copying stops as 
soon as either of the following occurs: 

■ The character c is first copied into dest . 
m n bytes have been copied into dest . 

memccpy returns a pointer to the byte in dest immediately following c, if c 
was copied; otherwise, memccpy returns NULL. 

memcpy, memmove, memset 



memchr, fmemchr 
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mem.h 



Function 
Syntax 



memchr 
fmemchr 



Remarks 



Searches n bytes for character c. 

void *memchr (const void *s, int c, size_t n) ; 

void far * far _fmemchr( const void far *s, int c, size_t n) 

const void *memchr (const void *s, int c, size_t n) ; 
void *memchr(void *s, int c, size_t n) ; 
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/* C only */ 

/* C and C++ */ 

// C++ only 
// C++ only 



memchr is available on UNIX System V systems. 

memchr searches the first n bytes of the block pointed to by s for character c. 
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memchr, Jmemchr 



Return value 



On success, memchr returns a pointer to the first occurrence of c in s; 
otherwise, it returns NULL. 

If you are using the intrinsic version of these functions, the case of n=0 will 
return NULL. 



memcmp, Jmemcmp 



mem.h 



Function 
Syntax 



memcmp 
jmemcmp 



Remarks 



Return value 



See also 



Compares two blocks for a length of exactly n bytes. 

int memcmp (const void *sl, const void *s2, size_t n) ; 

int far _fmemcmp( const void far *sl, const void far *s2, size_t n) 
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memcmp is available on UNIX System V systems. 

memcmp compares the first n bytes of the blocks si and s2 as unsigned 
chars. 

Because it compares bytes as unsigned chars, memcmp returns a value that 
is 

■ < if si is less than s2 

m = if si is the same as s2 

■ > if si is greater than s2 

For example, 

memcmp ("\xFF", "\x7F", 1) 

returns a value greater than 0. 

If you are using the intrinsic version of these functions, the case of n=0 will 
return NULL. 

memicmp 




memcpy, Jmemcpy 



mem.h 



Function 



Copies a block of n bytes. 
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memcpy, Jmemcpy 



Syntax 



memcpy 
Jmemcpy 



Remarks 



Return value 
See also 



void *memcpy(void *dest, const void *src, size_t n) ; ' 

void far * far _fmemcpy(void far *dest, const void far *src, size_t n) ; 
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memcpy is available on UNIX System V systems. 

memcpy copies a block of n bytes from src to dest. If src and dest overlap, the 
behavior of memcpy is undefined. 

memcpy returns dest . 

memccpy, memmove, memset, movedata, movmem 



memicmp, Jmemicmp 



mem.h 



Function 
Syntax 



memicmp 
Jmemicmp 



Remarks 



Return value 



See also 



Compares n bytes of two character arrays, ignoring case. 

int memicmp (const void *sl, const void *s2, size_t n) ; 

int far _fmemicmp( const 'void far *sl, const void far *s2, size_t n) 
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memicmp is available on UNIX System V systems. 

memicmp compares the first n bytes of the blocks si and s2, ignoring 
character case (upper or lower). 

memicmp returns a value that is 

■ < if si is less than s2 

■ = if si is the same as s2 
m > if si is greater than s2 

memcmp 



memmove, fmemmove 



mem.h 



Function 



Copies a block of n bytes. 
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memmove, Jmemmove 



Syntax 



memmove 
fmemmove 



Remarks 

Return value 
See also 



void * memmove (void *dest, const void,*src, size_t n) ; 

void far * far _fmemmove (void far *dest, const void far *src, size_t n) 
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memmove copies a block of n bytes from src to dest . Even when the source 
and destination blocks overlap, bytes in the overlapping locations are 
copied correctly. 

memmove returns dest. 

memccpy, memcpy, movmem 



memset, Jmemset 



mem.h 




Function 
Syntax 



memset 
fmemset 



Remarks 
Return value 
See also 



Sets n bytes of a block of memory to byte c. 

void *memset(void *s, int c, size_t ne- 
void far * far _fmemset (void far *s, int c, size_t n) 
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memset sets the first n bytes of the array s to the character c. 
memset returns s. 
memccpy, memcpy, setmem 



mm 



stdlib.h 



Function 
Syntax 



Returns the smaller of two values. 

(type) min(a, b) ; 

template <class T> T min( T tl, T t2 ); 
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mm 



Remarks 

Return value 
See also 



The C macro and the C++ template function compare two values and 
return the smaller of the two. Both arguments and the routine declaration 
must be of the same type. 

min returns the smaller of two values. 



max 



mkdir 



dir.h 



Function 
Syntax 



Remarks 



Return value 



See also 



Creates a directory. 

int mkdir (const char *path); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 






■ 



mkdir is available on UNIX, though it then takes an additional parameter. 

mkdir creates a new directory from the given path name -path. 

mkdir returns the value if the new directory was created. 

A return value of -1 indicates an error, and the global variable errno is set to 
one of the following values: 



EACCES 
ENOENT 



Permission denied 

No such file or directory 

chdir, getcurdir, getcwd, rmdir 



MK FP 



dos.h 



Function 
Syntax 



Remarks 
Return value 



Makes a far pointer. 

void far * MK_FP (unsigned seg, unsigned ofs); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 











MKJFP is a macro that makes a far pointer from its component segment 
(seg) and offset (ofs) parts. 

MKJFP returns a far pointer. 
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MK FP 



See also 



FPJDFF, FP_SEG, movedata, segread 



mktemp 



dir.h 



Function 
Syntax 



Remarks 



Return value 



Makes a unique file name. 

char *mktemp(char *template) ; 
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mktemp replaces the string pointed to by template with a unique file name 
and returns template. 

template should be a null-terminated string with six trailing Xs. These Xs 
are replaced with a unique collection of letters plus a period, so that there 
are two letters, a period, and three suffix letters in the new file name. 

Starting with AA.AAA, the new file name is assigned by looking up the 
name on the disk and avoiding pre-existing names of the same format. 

If template is well-formed, mktemp returns the address of the template string. 
Otherwise/it returns null. 




mktime 



time.h 



Function 
Syntax 



Remarks 



Converts time to calendar format. 

time_t mktime (struct tm *t); 
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Return value 



Converts the time in the structure pointed to by t into a calendar time with 
the same format used by the time function. The original values of the fields 
tm_sec, tmjnin, tmjiour, tmjnday, and tmjnon are not restricted to the 
ranges described in the tm structure. If the fields are not in their proper 
ranges, they are adjusted. Values for fields tmjwday and tmjyday dire 
computed after the other fields have been adjusted. If the calendar time 
cannot be represented, mkti me returns -1. 

The allowable range of calendar times is Jan 1 1970 00:00:00 to Jan 19 2038 
03:14:07. 

See Remarks. 
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mktime 



See also 



localtime, strftime, time 



modf, modfl 



math.h 



Function 
Syntax 



Remarks 



modf 
modfl 



Return value 
See also 



Splits a double or long double into integer and fractional parts. 

double modf (double x, double *ipart); 

long double modfl (long double x, long double *ipart); 
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modf breaks the double x into two parts: the integer and the fraction, modf 
stores the integer in ipart and returns the fraction. 

modfl is the long double version; it takes long double arguments and 
returns a long double result. 

modf and modfl return the fractional part of x. 

fmod, Idexp 



movedata 



mem.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Copies n bytes. 

void movedata (unsigned srcseg, unsigned srcoff, unsigned dstseg, unsigned dstoff, 
size_t n) ; 
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movedata copies n bytes from the source address (srcseg:srcoff) to the 
destination address (dstseg-.dstoff). movedata provides a memory-model inde- 
pendent means for moving blocks of data. 

None. 

FPJDFF, memcpy, MK_FP,movmem, segread 
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movmem, Jmovmem 



movmem, fmovmem 



mem.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Moves a block of length bytes. 

void movmem (const void *src, void *dest, unsigned length); 

void _fmovmem( const void far *src, void far *dest, unsigned length); 
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movmem moves a block of length bytes from src to dest. Even if the source 
and destination blocks overlap, the move direction is chosen so that the 
data is always moved correctly. Jmovmem provides the same functionality 
in a large memory model as movmem does in small memory model. 

None. 

memcpy, memmove, movedata 




movetext 



conio.h 



Function 
Syntax 



Remarks 



Return value 



See also 



Copies text onscreen from one rectangle to another. 

int movetext(int left, int top, int right, int bottom, int destleft, int desttop) ; 
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movetext copies the contents of the onscreen rectangle defined by left, top, 
right, and bottom to a new rectangle of the same dimensions. The new 
rectangle's upper left corner is position (destleft, desttop). 

All coordinates are absolute screen coordinates. Rectangles that overlap are 
moved correctly. 

movetext is a text mode function performing direct video output. 

This function should not be used in Win32s or Win32 GUI applications. 

movetext returns nonzero if the operation succeeded. If the operation failed 
(for example, if you gave coordinates outside the range of the current 
screen mode), movetext returns 0. 

gettext, puttext 



Chapter 3, Run-time functions 



181 



msize 



_msize 

Function 
Syntax 



Remarks 



Return value 
See also 



malloc.h 



Returns the size of a heap block. 

size_t jnsize (void *block) ; 
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jnsize returns the size of the allocated heap block whose address is block. 
The block must have been allocated with malloc, calloc, or realloc. The 
returned size can be larger than the number of bytes originally requested 
when the block was allocated. 

jnsize returns the size of the block in bytes. 

malloc, free, realloc -. 



normvideo 



conio.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Selects normal-intensity characters. 

void normvideo (void) ; 
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normvideo selects normal characters by returning the text attribute 
(foreground and background) to the value it had when the program 
started. 

This function does not affect any characters currently on the screen, only 
those displayed by functions (such as cprintf) performing direct console 
output functions after normvideo is called. 

This function should not be used in Win32s or Win32 GUI applications. 

None. 

highvideo, lowvideo, textattr, textcolor 



offsetof 



stddef.h 



Function 



Gets the byte offset to a structure member. 
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offsetof 



Syntax 



Remarks 



Return value 



size_t offsetof (struct_type, struct_member) ; 
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offsetof is available only as a macro. The argument structjype is a struct 
type, struct jnember is any element of the struct that can be accessed 
through the member selection operators or pointers. 

If structjnember is a bit field, the result is undefined. 

See also Chapter 2 in the Programmer's Guide for a discussion of the sizeof 
operator, memory allocation, and alignment of structures. 

offsetof returns the number of bytes from the start of the structure to the 
start of the named structure member. 



_open 



fcntl.h, share.h, dos.h 



Remarks 



open 



Obsolete function. See _rtl_open. 



fcntl.h, io.h 



Bffl 



Function 
Syntax 



Remarks 



Opens a file for reading or writing. 

int open (const char *path, int access [, unsigned mode] ) ; 
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open opens the file specified by path, then prepares it for reading and /or 
writing as determined by the value of access. 

To create a file in a particular mode, you can either assign to the global 
variable Jmode or call open with the 0_CREAT and OJTRUNC options 
ORed with the translation mode desired. For example, the call 

open ( " XMP " , 0_CREAT I 0_TRUNC I 0_BINARY , S_IREAD ) 

creates a binary-mode, read-only file named XMP, truncating its length to 
bytes if it already existed. 

For open, access is constructed by bitwise ORing flags from the following 
two lists. Only one flag from the first list can be used (and one must be 
used); the remaining flags can be used in any logical combination. 
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open 



These symbolic 

constants are defined 

in fcntl.h. 



List 1 : Read/write flags 

0_RDONLY Open for reading only. 

0_WRONLY Open for writing only. 

0_RDWR Open for reading and writing. 

List 2: Other access flags 

0_NDELAY Not used; for UNIX, compatibility. 

0_APPEND If set, the file pointer will be set to the end of the file 

prior to each write. 
0_CREAT If the file exists, this flag has no effect. If the file does 

not exist, the file is created, and the bits of mode are 

used to set the file attribute bits as in chmod. 
0_TRUNC If the file exists, its length is truncated to 0. The file 

attributes remain unchanged. 
0_EXCL Used only with 0_CREAT. If the file already exists, 

an error is returned. 
0_BINARY Can be given to explicitly open the file in binary 

mode. 
0_TEXT Can be given to explicitly open the file in text mode. 

If neither 0_BINARY nor 0_TEXT is given, the file is opened in the 
translation mode set by the global variable Jmode. 

If the 0_CREAT flag is used in constructing access, you need to supply the 
mode argument to open from the following symbolic constants defined in 
sys\stat.h. 



Return value 



Value of mode 



SJWRITE 

SJREAD 

S IREADIS IWRITE 



Access permission 



Permission to write 
Permission to read 
Permission to read and write 



On successful completion, open returns a nonnegative integer (the file 
handle). The file pointer, which marks the current position in the file, is set 
to the beginning of the file. On error, open returns -1 and the global variable 
errno is set to one of the following values: 



EACCES Permission denied 

EINVACC Invalid access code 

EMFILE Too many open files 

ENOENT No such file or directory 
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See also 



chmod, chsize, close, _rtl_creat, exeat, creatnew, creattemp, dup, dupl, fdopen, 
filelength, fopen, freopen, getftitne, Iseek, lock, _rtl_open, read, sopen, _rtl_write, 
write 



opendir 



dirent.h 



Function 
Syntax 



Remarks 



Return value 



Opens a directory stream for reading. 

DIR *opendir(char *dirname); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 






■ 



See also 



opendir is available on POSIX-compliant UNIX systems. 

The opendir function opens a directory stream for reading. The name of the 
directory to read is dirname. The stream is set to read the first entry in the 
directory. 

A directory stream is represented by the DIR structure, defined in dirent.h. 
This structure contains no user-accessible fields. Multiple directory streams 
can be opened and read simultaneously. Directory entries can be created or 
deleted while a directory stream is being read. 

Use the readdir function to read successive entries from a directory stream. 
Use the closedir function to remove a directory stream when it is no longer 
needed. 

If successful, opendir returns a pointer to a directory stream that can be used 
in calls to readdir, rewinddir, and closedir. If the directory cannot be opened, 
opendir returns NULL and sets the global variable errno to 

ENOENT The directory does not exist 

ENOMEM Not enough memory to allocate a DIR object 

closedir, readdir, rewinddir 



i 



outp 



conio.h 



Function 
Syntax 



Outputs a byte to a hardware port. 

int outp (unsigned portid, int value); 



DOS 
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Win 16 


Win 32 
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ANSI C++ 
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■ 
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outp 



Remarks 



Return value 
See also 



outp is a macro that writes the low byte of value to the output port specified 
by portid. 

If outp is called when conio.h has been included, it will be treated as a 
macro that expands to inline code. If you don't include conio.h, or if you do 
include conio.h and #undef the macro outp, you'll get the outp function. 

outp returns value. 

inp, inpw, outpw 



outport, outportb 



dos.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Outputs a word or byte to a hardware port. 

void outport (int portid, int value); 

void outportb(int portid, unsigned char value); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 
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■ 











outport works just like the 80x86 instruction OUT. It writes the low byte of 
the word given by value to the output port specified by portid and writes the 
high byte of the word to portid +1. . 

outportb is a macro that writes the byte given by value to the output port 
specified by portid. 

If outportb is called when dos.h has been included, it will be treated as a 
macro that expands to inline code. If you don't include dos.h, or if you do 
include dos.h and #undef the macro outportb, you'll get the outportb 
function. 

None. 

inport, inportb 



outpw 



conio.h 



Function 
Syntax 



Outputs a word to a hardware port. 

unsigned outpw (unsigned portid, unsigned value) ; 
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Remarks 



Return value 
See also 



outpw is a macro that writes the 16-bit word given by value to the output 
port specified by portid. It writes the low byte of value to portid, and the high 
byte of the word to portid +1, using a single 16-bit OUT instruction. 

If outpw is called when conio.h has been included, it will be treated as a 
macro that expands to inline code. If you don't include conio.h, or if you do 
include conio.h and #undef the macro outpw, you'll get the outpw function. 

outpw returns value. 

inp, inpw, outp 



parsfnm 



dos.h 



Function 
Syntax 



Remarks 



Return value 



Parses file name. 

char *parsfnm (const char *cmdline, struct fcb *fcb, int. opt); 
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■ 











parsfnm parses a string pointed to by cmdline for a file name. The string is 
normally a command line. The file name is placed in a file control block 
(FCB) as a drive, file name, and extension. The FCB is pointed to by fcb. 

The opt parameter is the value documented for AL in the DOS parse system 
call. See your DOS reference manuals under system call 0x29 for a 
description of the parsing operations performed on the file name. 

On success, parsfnm returns a pointer to the next byte after the end of the 
file name. If there is any error in parsing the file name, parsfnm returns null. 



HH 



_pclose 



stdio.h 



Function 
Syntax 



Remarks 



Waits for piped command to complete. 

int _pclose(FILE * stream); 



DOS 
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■ 



This function is not available in Win32s programs. 

jpclose closes a pipe stream created by a previous call to jpopen, and then 
waits for the associated child command to complete. 
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_pclose 



Return value 



See also 



If it is successful, jpclose returns the termination status of the child 
command. This is the same value as the termination status returned by 
cwait, except that the high and low order bytes of the low word are 
swapped. If jpclose is unsuccessful, it returns -1. 

_pipe, _popen 



peek 



dos.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Returns the word at memory location specified by segmenkoffset. 

int peek (unsigned segment, unsigned offset) ; 
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peek returns the word at the memory location segmenkoffset. 

If peek is called when dos.h has been included, it is treated as a macro that 
expands to inline code. If you don't include dos.h, or if you do include it 
and #undef peek, you'll get the function rather than the macro. 

peek returns the word of data stored at the memory location segmenkoffset. 

peekb, poke 



peekb 



dos.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Returns the byte of memory specified by segmenkoffset. 

char peekb (unsigned segment, unsigned offset); 
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peekb returns the byte at the memory location addressed by segmenkoffset. 

If peekb is called when dos.h has been included, it is treated as a macro that 
expands to inline code. If you don't include dos.h, or if you do include it 
and #undef peekb, you'll get the function rather than the macro. 

peekb returns the byte of information stored at the memory location 

segmenkoffset. 

peek,pokeb 
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perror 

Function 
Syntax 



Remarks 



stdio.h 



Table 3.2 

These messages are 

generated in both 

Win 16 and Win 32. 



Prints a system error message. 

void perror(const char *s); 
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perror prints to the stderr stream (normally the console) the system error 
message for the last library routine that set errno. 

First the argument s is printed, then a colon, then the message corre- 
sponding to the current value of the global variable errno, and finally a 
newline. The convention is to pass the file name of the program as the 
argument string. 

The array of error message strings is accessed through the global variable 
_sys_errlist. The global variable errno can be used as an index into the array 
to find the string corresponding to the error number. None of the strings 
include a newline character. 

The global variable _sys_nerr contains the number of entries in the array. 

Refer to errno, _sys_errlist, and _sys_nerr in Chapter 4 for more information. 

The following messages are generated by perror: 

Win 16 and Win 32 messages 



Q3 



Arg list too big 

Attempted to remove current 

directory 
Bad address 
Bad file number 
Block device required 
Broken pipe 
Cross-device link 
Error 

Exec format error 
Executable file in use 
File already exists 
File too large 
Illegal seek 
Inappropriate I/O control 

operation 
Inputibutput error 
Interrupted function call 



Is a directory 

Math argument 

Memory arena trashed 

Name too long 

No child processes 

No more files 

No space left on device 

No such device 

No such device or address 

No such file or directory 

No such process 

Not a directory 

Not enough memory 

Not same device 

Operation not permitted 

Path not found 

Permission denied 

Possible deadlock 
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perror 



Table 3.2: These messages are generated in both Win 16 and Win 32. (continued) 



Table 3.3 

These messages are 

generated only in 

Win 32. 



Return value 
See also 



Invalid access code 

Invalid argument 

Invalid data 

Invalid environment 

Invalid format 

Invalid function number 

Invalid memory block address 



Win 32-only messages 



Bad address 
Block device required 
Broken pipe 
Executable file in use 
File too large 
Illegal seek 
Inappropriate I/O control 

operation 
Inputibutput error 
Interrupted function call 
Is a directory 
Name too long 



Read-only file system 

Resource busy 

Resource temporarily unavailable 

Result too large 

Too many links 

Too many open files 



No child processes 

No space left on device 

No such device or address 

No such process 

Not a directory 

Operation not permitted 

Possible deadlock 

Read-only file system 

Resource busy 

Resource temporarily unavailable 

Too many links 



For Win32s or Win32 GUI applications, stderr must be redirected. 

None. 

clearerr, eof, freopen, _strerror, strerror 



.pipe 



fcntl.h, io.h 



Function 
Syntax 



Remarks 



Creates a read /write pipe. 

int _pipe(int *handles, unsigned int size, int mode); 



DOS 
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■ 



This function is not available in Win32s programs. 

The _pipe function creates an anonymous pipe that can be used to pass 
information between processes. The pipe is opened for both reading and 
writing. Like a disk file, a pipe can be read from and written to, but it does 
not have a name or permanent storage associated with it; data written to 
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and from the pipe exist only in a memory buffer managed by the operating 
system. 

The read handle is returned to handles[0], and the write handle is returned 
to handles[\]. The program can use these handles in subsequent calls to read, 
write, dup, dup2, or close. When all pipe handles are closed, the pipe is 
destroyed. 

The size of the internal pipe buffer is size. A recommended minimum value 
is 512 bytes. 

The translation mode is specified by mode, as follows: 



Return value 



See also 



OJBINARY The pipe is opened in binary mode 
0_TEXT The pipe is opened in text mode 

If mode is zero, the translation mode is determined by the external variable 
Jmode. 

On successful completion, _pipe returns and returns the pipe handles to 
handles[0] and handles[l]. Otherwise it returns -1 and sets errno to one of the 
following values: 

EMFILE Too many open files 
ENOMEM Out of memory 

jpclose, _popen 




poke 



dos.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Stores an integer value at a memory location given by segment.offset. 

void poke(unsigned segment, unsigned offset, int value); 
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■ 











poke stores the integer value at the memory location segmenhoffset. 

If this routine is called when dos.h has been included, it will be treated as a 
macro that expands to inline code. If you don't include dos.h, or if you do 
include it and #undef poke, you'll get the function rather than the macro. 

None. 

peek,pokeb 
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poKeo 



pokeb 

Function 
Syntax 



Remarks 



dos.h 



Return value 
See also 



Stores a byte value at memory location segmen t'.offset. 

void pokeb (unsigned segment, unsigned offset, char value); 
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pokeb stores the byte value at the memory location segmenkoffset. 

If this routine is called when dos.h has been included, it will be treated as a 
macro that expands to inline code. If you don't include dos.h, or if you do 
include it and #undef pokeb, you'll get the function rather than the macro. 

None. 

peekb,poke 



poly, polyl 



math.h 



Function 
Syntax 



Remarks 



poly 
polyl 



Return value 



Generates a polynomial from arguments. 

double poly(double x, int degree, double coeffs[]); 

long double polyl (long double x, int degree, long double coeffs[] 
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poly generates a polynomial in x, of degree degree, with coefficients coeffs[0], 
coeffs[l], ..., coeffsldegree]. For example, if n = 4, the generated polynomial is 

coeffsl^x 4 + coeffstflx 3 + coeffs[2]x z + coeffs[l]x + coeffs[0] 

polyl is the long double version; it takes long double arguments and returns 
a long double result. 

poly and polyl return the value of the polynomial as evaluated for the 
given x. 



_popen 



stdio.h 



Function 



Creates a command processor pipe. 
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Syntax 



Remarks 



FILE *_popen (const char •* command, const char *mode) ; 
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■ 



This function is not available in Win32s programs. 

The _popen function creates a pipe to the command processor. The 
command processor is executed asynchronously, and is passed the 
command line in command. The mode string specifies whether the pipe is 
connected to the command processor's standard input or output, and 
whether the pipe is to be opened in binary or text mode. 

The mode string can take one of the following values: 



Value 



Description 



Return value 



See also 



rt Read child command's standard output (text). 

rb Read child command's standard output (binary). 

wt Write to child commands standard input (text). 

wb Write to child commands standard input (binary). 



The terminating t or b is optional; if missing, the translation mode is 
determined by the external variable Jmode. 

Use the jpclose function to close the pipe and obtain the return code of the 
command. 

If _popen is successful it returns a FILE pointer that can be used to read the 
standard output of the command, or to write to the standard input of the 
command, depending on the mode string. If _popen is unsuccessful, it 
returns NULL. 

_pclose, _pipe 




pow, powl 



math.h 



Function 



Calculates x to the power of y. 
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pow, powl 



Syntax 



pow 
powl 



Remarks 



Return value 



See also 



double pow.( double x, double y) ; 

long double powl (long double x, double y), 
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pow calculates xV. ' . . 

powl is the long double version; it takes long double arguments and returns 
a long double result. 

This function can be used with bed and complex types. 

On success, pow and powl return the value calculated, x#. 

Sometimes the arguments passed to these functions produce results that 
overflow or are incalculable. When the correct value would overflow, the 
functions return the value HUGE_VAL (pow) or _LHUGE_VAL (powl). 
Results of excessively large magnitude can cause the global variable errno 
to be set to 

ERANGE Result out of range 

If the argument x passed to pow or powl is real and less than 0, and y is not a 
whole number, or you call pow( 0, ), the global variable errno is set to 



EDOM 



Domain error 



Error handling for these functions can be modified through the functions 
jnatherr and jnatherrl. 

bed, complex, exp, powlO, sqrt 



pow10,pow10l 



math.h 



Function 
Syntax 



pow10 
powWI 



Remarks 



Calculates 10 to the power of p. 

double powlOfint p) ; 

long double powl01(int p) ; 
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powlO computes 10 p . 
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pow10, powlOI 



Return value 



See also 



On success, powlO returns the value calculated, 10 p . 

The result is actually calculated to long double accuracy. All arguments are 
valid, although some can cause an underflow or overflow. 

powl is the long double version; it returns a long double result. 

exp,pow 



printf 



stdio.h 



Function 
Syntax 



Remarks 



The format string 



Writes formatted output to stdout. 

int printf (const char * format [, argument, ...]); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 




■ 


■ 


■ 


■ 



printf accepts a series of arguments, applies to each a format specifier 
contained in the format string given by format, and outputs the formatted 
data to stdout. There must be the same number of format specifiers as 
arguments. 

For Win32s or Win32 GUI applications, stdout must be redirected. 

The format string, present in each of the ...printf function calls, controls 
how each function will convert, format, and print its arguments. There must 
be enough arguments for the format; if not, the results will be unpredictable and 
possibly disastrous. Excess arguments (more than required by the format) are 
ignored. 

The format string is a character string that contains two types of objects — 
plain characters and conversion specifications: 

u Plain characters are copied verbatim to the output stream. 

■ Conversion specifications fetch arguments from the argument list and 
apply formatting to them. 

Format specifiers 

. . .printf format specifiers have the following form: 

.% [flags] [width] [.prec] [F|N|h|l|L] type 



I 
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printf 



Optional format 
string components 



Each format specifier begins with the percent character (%). After the % 
come the following, in this order: 

■ An optional sequence of flag characters, [ flags ] 
b An optional width specifier, [width] 

d An optional precision specifier, [ .prec] 

■ An optional input-size modifier, [ F I N I h 1 1 1 L ] 

■ The conversion-type character, [type] 

These are the general aspects of output formatting controlled by the 
optional characters, specifiers, and modifiers in the format string: 



...printf 

conversion-type 

characters 



Character 
or specifier 



What it controls or specifies 



Flags Output justification, numeric signs, decimal points, trailing zeros, octal and hex 

prefixes 

Width Minimum number of characters to print, padding with blanks or zeros 

Precision Maximum number of characters to print; for integers, minimum number of 

digits to print 

Size Override default size of argument: 

N = near pointer 
F = far pointer 
h = short int 
I = long 
L = long double 

The following table lists the ...printf conversion-type characters, the type of 
input argument accepted by each, and in what format the output appears. 

The information in this table of type characters is based on the assumption 
that no flag characters, width specifiers, precision specifiers, or input-size 
modifiers were included in the format specifiers. To see how the addition of 
the optional characters and specifiers affects the ...printf output, refer to the 
tables following this one. 



Type 
character 



Input argument 



Format of output 



Numerics 



d 


Integer 


signed decimal int. 


i 


Integer 


signed decimal int. 





Integer 


unsigned octal int. 


u 


Integer 


unsigned decimal int. 
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X 


Integer 


X 


Integer 


f 


Floating-point 


e 


Floating-point 


g 


Floating-point 


E 


Floating-point 


G 


Floating-point 


Characters 




c 


Character 


s 


String pointer 


% 


None 


Pointers 




n 


Pointer to int 



Pointer 



unsigned hexadecimal int (with a, b, c, d, e, f). 
unsigned hexadecimal int (with A, B, C, D, E, F). 

signed value of the form [-]dddd.dddd. 

signed value of the form [-]d.dddd or e [+/-]ddd. 

signed value in either e or f form, based on given value and precision. 

Trailing zeros and the decimal point are printed only if necessary. 

Same as e, but with E for exponent. 

Same as g, but with E for exponent if e format used. 



Single character. 

Prints characters until a null-terminator is pressed or precision is reached. 

The % character is printed. 



Stores (in the location pointed to by the input argument) a count of the 
characters written so far. 

Prints the input argument as a pointer; format depends on which memory model 
was used. It will be either XXXX.-YYYY or YYYY (offset only). 



Conventions Certain conventions accompany some of these specifications. The decimal- 
point character used in the output is determined by the current locale's 
LC_NUMERIC category. The conventions are summarized in the following 
table: 



I 



Characters 



Conventions 



e or E The argument is converted to match the style [-] d.ddd. . .e[+l-]ddd, where 

■ One digit precedes the decimal point. 

■ The number of digits after the decimal point is equal to the precision. 

■ The exponent always contains at least two digits. 

f The argument is converted to decimal notation in the style [-] ddd.ddd..., where 

the number of digits after the decimal point is equal to the precision (if a nonzero 
precision was given). 

g or G The argument is printed in style e, E or f , with the precision specifying the 

number of significant digits. Trailing zeros are removed from the result, and a 
decimal point appears only if necessary. 
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Characters Conventions 



The argument is printed in style e or f (with some restraints) if g is the 
conversion character, and in style E if the character is G. Style e is used only if 
the exponent that results from the conversion is either greater than the precision 
or less than -4. 

. x or X For x conversions, the letters a, b, c, d, e, and f appear in the output; for X 

conversions, the letters A, B, C, D, E, and F appear. 

b^- Infinite floating-point numbers are printed as +INF and -INF. An IEEE 
Not-a-Number is printed as +NAN or -NAN. 

Flag characters The flag characters are minus (-), plus (+), sharp (#), and blank (). They can 
appear in any order and combination. 



Flag 



What it specifies 



Left-justifies the result, pads on the right with blanks. If not given, it right-justifies the 
result, pads on the left with zeros or blanks. 

+ Signed conversion results always begin with a plus (+) or minus (-) sign. 

blank If value is nonnegative, the output begins with a blank instead of a plus; negative 
values still begin with a minus. 

# Specifies that arg is to be converted using an "alternate form." See the following table. 

ta^- Plus '(+) takes precedence over blank () if both are given. 

Alternate forms If the # flag is used with a conversion character, it has the following effect 
on the argument (arg) being converted: 



Conversion 
character 



How # affects arg 



c,s,d,i,u No effect. 

is prepended to a nonzero arg. 

xorX Ox (or OX) is prepended to arg. 

e, E, or f The result always contains a decimal point even if no digits follow the point. 

Normally, a decimal point appears in these results only if a digit follows it. 

gorG - Same as e and E, with the addition that trailing zeros are not removed. 

Width specifiers The width specifier sets the minimum field width for an output value. 

Width is specified in one of two ways: directly, through a decimal digit 
string, or indirectly, through an asterisk (*). If you use an asterisk for the 
width specifier, the next argument in the call (which must be an int) 
specifies the minimum output field width. 
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In no case does a nonexistent or small field width cause truncation of a 
field. If the result of a conversion is wider than the field width, the field is 
simply expanded to contain the conversion result. 

Width 

specifier How output width is affected 

n At least n characters are printed. If the output value has less than n characters, 

the output is padded with blanks (right-padded if - flag given, left-padded 
otherwise). 

On At least n characters are printed. If the output value has less than n characters, it 

is filled on the left with zeros. 

* The argument list supplies the width specifier, which must precede the actual 

argument being formatted. 

Precision specifiers A precision specification always begins with a period (.) to separate it from 
any preceding width specifier. Then, like width, precision is specified either 
directly through a decimal digit string, or indirectly through an asterisk (*). 
- If you use an asterisk for the precision specifier, the next argument in the 
call (treated as an int) specifies the precision. 

If you use asterisks for the width or the precision, or for both, the width 
argument must immediately follow the specifiers, followed by the precision 
argument, then the argument for the data to be converted. 

Precision ' 

specifier How output precision is affected 

(none given) Precision set to default: 

default = 1 for d, /, o, u, x, X types 

default = 6 for e, E, /types 

default = all significant digits for g, G types 

default = print to first null character for s types; no effect on c types 

.0 For d, ;', o, u, x types, precision set to default; for e, E, f types, no decimal point 

is printed. 

.n n characters or n decimal places are printed. If the output value has more than 

n characters, the output might be truncated or rounded. (Whether this happens 
depends on the type character.) 

.* . The argument list supplies the precision specifier, which must precede the 

actual argument being formatted. 

fc^- If an explicit precision of zero is specified, and the format specifier for the 
field is one of the integer formats (that is, d, i, o, u, x), and the value to be 
printed is 0, no numeric characters will be output for that field (that is, the 
field will be blank). 
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printf 



Conversion 

character How precision specification (.n) affects conversion 

d .n specifies that at least n digits are 

i printed. If the input argument has less 

o than n digits, the output value is left- 

u padded with zeros. If the input argument 

x has more than n digits, the output value 

X , is not truncated. 

e .n specifies that n characters are printed 

E after the decimal point, and the last digit 

f printed is rounded. 

g .n specifies that at most n significant 

G digits are printed. 

c .n has no effect on the output. 

s .n specifies that no more than n characters 

are printed. 

Input-size modifier The input-size modifier character (F, N, h, I, or L) gives the size of the 
subsequent input argument: 

F = far pointer 
N = near pointer 
h = short int 
/ = long 
L = long double 

The input-size modifiers (F, N, h, I, and L) affect how the . . .printf functions 
interpret the data type of the corresponding input argument arg. F and N 
apply only to input args that are pointers (%p, %s, and %n). h, L, and L 
apply to input args that are numeric (integers and floating-point). 

Both F and N reinterpret the input arg. Normally, the arg for a %p, %s, or 
%n conversion is a pointer of the default size for the memory model. F 
means "interpret arg as a far pointer." N means "interpret arg as a near 
pointer." 

h, I, and L override the default size of the numeric data input arguments: / 
and L apply to integer (d, i, o, u, x, X) and floating-point (e, E, f, g, and G) 
types, while h applies to integer types only. Neither h nor / affect character 
(c, s) or pointer (p, n) types. 
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Return value 
See also 



Input-size 
modifier 



How arg is interpreted 



F arg is read as a far pointer. 

N arg is read as a near pointer. N cannot be used with any conversion in huge 

model. 

h ' arg is interpreted as a short int for d, i, o, u, x, or X. 

/ arg is interpreted as a long int for d, i, o, u, x, or X; arg is interpreted as a 

double for e, E, f, g, or G. 

L arg is interpreted as a long double for e, E, f, g, or G. 

printf returns the number of bytes output. In the event of error, printf 
returns EOF. 

cprintf, ecvt, fprintf, fread, freopen, fscanf, putc, puts, putw, scanf, sprintf, vprintf, 
vsprintf 



putc 



stdio.h 



Function 
Syntax 



Remarks 
Return value 
See also 



Outputs a character to a stream. 

int putc (int c, FILE *stream) ; 
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putc is a macro that outputs the character c to the stream given by stream. 

On success, putc returns the character printed, c. On error, putc returns EOF. 

fprintf, fputc, fputchar, fputs, fwrite, getc, getchar, printf, putch, putchar, putw, 
vprintf ' 



putch 



conio.h 



Function 
Syntax 



Outputs character to screen. 

int putch (int c) ; 
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putch 



Remarks 



Return value 
See also 



putch outputs the character c to the current text window. It is a text mode 
function performing direct video output to the console, putch does not 
translate linefeed characters (\n) into carriage-return/linefeed pairs. 

The string is written either directly to screen memory or by way of a BIOS 
call, depending on the value of the global variable directvideo. 

This function should not be used in Win32s or Win32 GUI applications. 

On success, putch returns the character printed, c. On error, it returns EOF. 

cprintf, cputs, getch, getche, putc, putchar 



putchar 



stdio.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Outputs character on stdout. 

int putchar (int c) ; 
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putchar(c) is a macro defined to be putc(c, stdout). 

For Win32s or Win32 GUI applications, stdout must be redirected. 

On success, putchar returns the character c. On error, putchar returns EOF. 

fputchar, getc, getchar, printf, putc, putch, puts, putw, freopen, vprintf 



putenv 



stdlib.h 



Function 
Syntax 



Remarks 



Adds string to current environment. 

int putenv,(const char *name); 
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putenv accepts the string name and adds it to the environment of the current 
process. For example, 

putenv("PATH=C:\\BC"); 

putenv can also be used to modify an existing name. On DOS and OS/2, 
name must be uppercase. On other systems, name can be either uppercase or 
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putenv 



Return value 
See also 



lowercase, name must not include the equal sign (=). You can set a variable 
to an empty value by specifying an empty string on the right side of the '=' 
sign. This effectively removes the environment variable. Environment 
variables created by putenv can be lower or upper case. 

putenv can be used only to modify the current program's environment. 
Once the program ends, the old environment is restored. The environment 
of the current process is passed to child processes, including any changes 
made by putenv. 

Note that the string given to putenv must be static or global, Unpredictable 
results will occur if a local or dynamic string given to putenv is used after 
the string memory is released. 

On success, putenv returns 0; on failure, -1. 

getenv 



puts 



stdio.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Outputs a string to stdout. 

int puts (const char *s); 
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puts copies the null-terminated string s to the standard output stream 
stdout and appends a newline character. 

For Win32s or Win32 GUI applications, stdout must be redirected. 

On successful completion, puts returns a nonnegative value. Otherwise, it 
returns a value of EOF. 

cputs,fputs,gets,printf,putchar f freopen 



puttext 



conio.h 



Function 
Syntax 



Copies text from memory to the text mode screen. 

int puttext (int left, int top, int right, int bottom, void *source) 
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puttext 



Remarks 



Return value 



See also 



puttext writes the contents of the memory area pointed to by source out to 
the onscreen rectangle defined by left, top, right, and bottom. 

All coordinates are absolute screen coordinates, not window-relative. The 
upper left corner is (1,1). 

puttext places the contents of a memory area into the defined rectangle 
sequentially from left to right and top to bottom. 

Each position onscreen takes 2 bytes of memory: The first byte is the 
character in the cell, and the second is the cell's video attribute. The space 
required for a rectangle w columns wide by h rows high is defined as 

bytes = (h rows) x (w columns) x 2 

puttext is a text mode function performing direct video output. 

This function should not be used in Win32s or Win32 GUI applications. 

puttext returns a nonzero value if the operation succeeds; it returns if it 
fails (for example, if you gave coordinates outside the range of the current 
screen mode). 

gettext, movetext, window 



putw 



stdio.h 



Function 
Syntax 



Remarks 
Return value 
See also 



Puts an integer on a stream. 

int putw(int w, FILE *stream) ; 
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putw outputs the integer w to the given stream, putw neither expects nor 
causes special alignment in the file. 

On success, putw returns the integer w. On error, putw returns EOF. Because 
EOF is a legitimate integer, use ferror to detect errors with putw. 

getw, print f 



qsort 



stdlib.h 



Function 



Sorts using the quicksort algorithm. 
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Syntax 



Remarks 



Return value 
See also 



void qsort (void *base, size_t nelem, size_t width, 

int (_USERENTRY *fcmp) (const void *, const void *) 
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qsort is an implementation of the "median of three" variant of the quicksort 
algorithm, qsort sorts the entries in a table by repeatedly calling the user- 
defined comparison function pointed to by fcmp. 

■ base points to the base (Oth element) of the table to be sorted. 

■ nelem is the number of entries in the table. 

■ width is the size of each entry in the table, in bytes. 

fcmp, the comparison function, must be used with the JUSERENTRY calling 
convention. 

fcmp accepts two arguments, eleml and eleml, each a pointer to an entry in 
the table. The comparison function compares each of the pointed-to items 
(*eleml and *elem2), and returns an integer based on the result of the 
comparison. 

■ *eleml < *eleml fcmp returns an integer < 



*eleml == *elem2 
*eleml > *eleml 



fcmp returns 

fcmp returns an integer > 



In the comparison, the less-than symbol (<) means the left element should 
appear before the right element in the final, sorted sequence. Similarly, the 
greater-than (>) symbol means the left element should appear after the 
right element in the final, sorted sequence. 

None. 

bsearch, Isearch 
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raise 



signal.h 



Function 
Syntax 



Sends a software signal to the executing program. 

int raise(int sig) ; 
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raise 



Remarks 



raise sends a signal of type sig to the program. If the program has installed a 
signal handler for the signal type specified by sig, that handler will be 
executed. If no handler has been installed, the default action for that signal 
type will be taken. 

The signal types currently defined in signal.h are noted here: 



Signal 


Description 


SIGABRT 


Abnormal termination 


SIGFPE 


Bad floating-point operation 


SIGILL 


Illegal instruction 


SIGINT 


Ctrl-C interrupt 


SIGSEGV 


Invalid access to storage 


SIGTERM 


Request for program termination 


SIGUSR1 


User-defined signal 


SIGUSR2 


User-defined signal 


SIGUSR3 


User-defined signal 


SIGBREAK 


Ctrl-Break interrupt 



Return value 
See also 



SIGABRT isn't generated by Borland C++ during normal operation. 
However, it can be generated by abort, raise, or unhandled exceptions. 

raise returns if successful, nonzero otherwise. 

abort, signal 



rand 



stdlib.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Random number generator. 

inf rand (void) ; 
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rand uses a multiplicative congruential random number generator with 
period 2 32 to return successive pseudorandom numbers in the range from 
to RAND_MAX. The symbolic constant RAND_MAX is defined in stdlib.h. 

rand returns the generated pseudorandom number. 

random, randomize, srand 
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random 



random 

Function 
Syntax 



Remarks 

Return value 
See also 



stdlib.h 



Random number generator. 

int random (int num) ; 
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random returns a random number between and (num-1). random(num) is a 
macro defined in stdlib.h. Both num and the random number returned are 
integers. 

random returns a number between and (num-1). 

rand, randomize, srand 



randomize 



stdlib.h, time.h 



Function 
Syntax 



Remarks 
Return value 
See also 



read 



Initializes random number generator. 

void randomize (void) ; 
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randomize initializes the random number generator with a random value. 
None. [ft 

rand, random, srand 

io.h, dos.h 




Remarks 



Obsolete function. See rtl read. 



read 



io.h 



Function 
Syntax 



Reads from file. 

int read (int handle, void *buf, unsigned len) 
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read 



Remarks 



Return value 
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read attempts to read len bytes from the file associated with handle into the 
buffer pointed to by buf. 

For a file opened in text mode, read removes carriage returns and reports 
end-of-file when it reaches a Ctrl-Z. 

The file handle handle is obtained from a creat, open, dup, or dup2 call. 

On disk files, read begins reading at the current file pointer. When the 
reading is complete, it increments the file pointer by the number of bytes 
read. On devices, the bytes are read directly from the device. 

The maximum number of bytes that read can read is UINT_MAX -1, 
because UINT_MAX is the same as -1, the error return indicator. 
UINT_MAX is defined in limits.h. 

On successful completion, read returns an integer indicating the number of 
bytes placed in the buffer. If the file was opened in text mode, read does not 
count carriage returns or Ctrl-Z characters in the number of bytes read. 

On end-of-file, read returns 0. On error, read returns -1 and sets the global 
variable errno to one of the following values: 



See also 



EACCES 
EBADF 



Permission denied 
Bad file number 



open, _rtl_read, write 



readdir 



dirent.h 



Function 
Syntax 



Remarks 



Reads the current entry from a directory stream. 

struct dirent * readdir (DIR *dirp) ; 
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readdir is available on POSIX-compliant UNIX systems. 

The readdir function reads the current directory entry in the directory 
stream pointed to by dirp. The directory stream is advanced to the next 
entry. 
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readdir 



Return value 



See also 



The readdir function returns a pointer to a dirent structure that is overwrit- 
ten by each call to the function on the same directory stream. The structure 
is not overwritten by a readdir call on a different directory stream. 

The dirent structure corresponds to a single directory entry. It is defined in 
dirent.h, and contains (in addition to other non-accessible members) the 
following member: 

char d_name [ ] ; 

where djname is an array of characters containing the null-terminated file 
name for the current directory entry. The size of the array is indeterminate; 
use strlen to determine the length of the file name. 

All valid directory entries are returned, including subdirectories, "." and 
".." entries, system files, hidden files, and volume labels. Unused or deleted 
directory entries are skipped. 

A directory entry can be created or deleted while a directory stream is 
being read, but readdir might or might not return the affected directory 
entry. Rewinding the directory with rewinddir or reopening it with opendir 
ensures that readdir will reflect the current state of the directory. 

If successful, readdir returns a pointer to the current directory entry for the 
directory stream. If the end of the directory has been reached, or dirp does 
not refer to an open directory stream, readdir returns NULL. 

closedir, opendir, rewinddir 



realloc 



stdlib.h 




Function 
Syntax 



Reallocates main memory. 

void *realloc(void *block, size_t size); 



Remarks 
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realloc attempts to shrink or expand the previously allocated block to size 
bytes. If size is zero, the memory block is freed and NULL is returned. The 
block argument points to a memory block previously obtained by calling 
malloc, calloc, or realloc. If block is a NULL pointer, realloc works just like 
malloc. 

realloc adjusts the size of the allocated block to size, copying the contents to 
a new location if necessary. 
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realloc 



Return value 



See also 



realloc returns the address of the reallocated block, which can be different 
than the address of the original block. If the block cannot be reallocated, 
realloc returns NULL. 

If the value of size is 0, the memory block is freed and realloc returns NULL. 

calloc, farrealloc, free, malloc 



remove 



stdio.h 



Function 
Syntax 



Remarks 



Return value 



Removes a file. 

int remove(const char *filename); 
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remove deletes the file specified by filename. It is a macro that simply 
translates its call to a call to unlink. If your file is open, be sure to close it 
before removing it. 

The filename string can include a full path. 

On successful completion, remove returns 0. On error, it returns -1, and the 
global variable errno is set to one of the following values: 



See also 



EACCES Permission denied 
ENOENT No such file or directory 

unlink 



rename 



stdio.h 



Function 
Syntax 



Remarks 



Renames a file. 

int rename (const char *oldname, const char *newname); 
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rename changes the name of a file from oldname to newname. If a drive 
specifier is given in newname, the specifier must be the same as that given in 
oldname. 
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rename 



Return value 



Directories in oldname and newname need not be the same, so rename can be 
used to move a file from one directory to another. Wildcards are not 
allowed. 

This function will fail (EACCES) if either file is currently open in any 
process. 

On successfully renaming the file, rename returns 0. In the event of error, -1 
is returned, and the global variable errno is set to one of the following 
values: 

EACCES Permission denied: filename already exists or has an 

invalid path 
ENOENT No such file or directory 
ENOTSAM Not same device 



rewind 



stdio.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Repositions a file pointer to the beginning of a stream. 

void rewind(FILE * stream) ; 
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rewind(stream) is equivalent to fseek(stream, 0L, SEEK_SET), except that 
rewind clears the end-of-file and error indicators, while fseek clears the end- 
of-file indicator only. 

After rewind, the next operation on an update file can be either input or 
output. 

None. 

fopen, fseek, f tell 




rewinddir 



dirent.h 



Function 
Syntax 



Resets a directory stream to the first entry. 

void rewinddir (DIR *dirp) ; 
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rewinddir 



Remarks 



Return value 
See also 



rewinddir is available on POSIX-compliant UNIX systems. 

The rewinddir function repositions the directory stream dirp at the first entry 
in the directory. It also ensures that the directory stream accurately reflects 
any directory entries that might have been created or deleted since the last 
opendir or rewinddir on that directory stream. 

None. 

closedir, opendir, readdir 



rmdir 



dir.h 



Function 
Syntax 



Remarks 



Return value 



Removes a directory. 

int rmdir (const char *path); 
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See also 



rmdir deletes the directory whose path is given by path. The directory 
named by path 

■ Must be empty 

■ Must not be the current working directory 

■ Must not be the root directory 

rmdir returns if the directory is successfully deleted. A return value of -1 
indicates an error, and the global variable errno is set to one of the following 
values: 

EACCES Permission denied 
ENOENT Path or file function not found 

chdir, getcurdir, getcwd, mkdir 



rmtmp 



stdio.h 



Function 
Syntax 



Removes temporary files. 

int rmtmp (void) ; 
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rmtmp 



Remarks 

Return value 
See also 



The rmtmp function closes and deletes all open temporary file streams, 
which were previously created with tmpfile. The current directory must the 
same as when the files were created, or the files will not be deleted. 

rmtmp returns the total number of temporary files it closed and deleted. 

tmpfile 



.rotl, _rotr 



stdlib.h 



Function 
Syntax 



Remarks 



Return value 



See also 



rtl chmod 



Bit-rotates an unsigned short integer value to the left or right. 

unsigned short _rotl (unsigned short value, int count); 
unsigned short _rotr (unsigned short value, int count); 
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_rotl rotates the given value to the left count bits. 
_rotr rotates the given value to the right count bits. 
The functions return the rotated integer: 

■ _rotl returns the value of value left-rotated count bits. 

■ _rotr returns the value of value right-rotated count bits. 

_crotl, _crotr, Jrotl, Jrotr 



dos.h, io.h 
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Function 
Syntax 



Remarks 



Gets or sets file attributes. 

int _rtl_chmod (const char *path, int func [, int attrib] ) ; 
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_rtl_chmod can either fetch or set file attributes, lifunc is 0, _rtl_chmod 
returns the current attributes for the file, lifunc is 1, the attribute is set to 
attrib. 

attrib can be one of the following symbolic constants (defined in dos.h): 



FA_RDONLY 
FA HIDDEN 



Read-only attribute 
Hidden file 
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rtl chmod 



Return value 



See also 



FA_SYSTEM 
FA_LABEL 
FA_DIREC 
FA ARCH 



System file 
Volume label 
Directory 
Archive 



Upon successful completion, _rtl_chmod returns the file attribute word; 
otherwise, it returns a value of -1. 

In the event of an error, the global variable errno is set to one of the 
following: 

EACCES Permission denied 
ENOENT Path or file name not found 

chmod, _rtl_creat 



rtl close 



io.h 



Function 
Syntax 



Remarks 



Return value 



Closes a file. 

int _rtl_close(int handle); 
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See also 



_rtl_close closes the file associated with handle, a file handle obtained from a 
_rtl_creat, creat, creatnew, creattemp, dup, dup2, _rtl_open, or open call. 

The function does not write a Ctrl-Z character at the end of the file. If you 
want to terminate the file with a Ctrl-Z, you must explicitly output one. 

Upon successful completion, _rtl_close returns 0. Otherwise, the function 
returns a value of -1. 

_rtl_close fails if handle is not the handle of a valid, open file, and the global 
variable errno is set to 

EBADF Bad file number 

chsize, close, creatnew, dup, fclose, _rtl_creat, _rtl_open, sopen 



rtl creat 



dos.h, io.h 



Function 
Syntax 



Creates a new file or overwrites an existing one. 

int _rtl_creat (const char *path, int attrib) ; 
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rtl creat 



Remarks 



Return value 
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See also 



_rtl_creat opens the file specified by path. The file is always opened in 
binary mode. Upon successful file creation, the file pointer is set to the 
beginning of the file. The file is opened for both reading and writing. 

If the file already exists, its size is reset to 0. (This is essentially the same as 
deleting the file and creating a new file with the same name.) 

The attrib argument is an ORed combination of one or more of the 
following constants (defined in dos.h): 

FA_RDONLY Read-only attribute 
FA_HIDDEN Hidden file 
FA.SYSTEM System file 

Upon successful completion, _rtl_creat returns the new file handle, a non- 
negative integer; otherwise, it returns -1. 

In the event of error, the global variable errno is set to one of the following 
values: 

EACCES Permission denied 
EMFILE Too many open files 
ENOENT Path or file name not found 

chsize, close, creat, creatnew, creattemp, _rtl_chmod, _rtl_close 



_rtl_heapwalk 



malloc.h 



QQ 



Function 
Syntax 



Remarks 



Inspects the heap, node by node. 

int _rtl_heapwalk(_HEAPINFO *hi) ; 
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_rtl_heapwalk assumes the heap is correct. Use Jieapchk to verify the heap 
before using _rtl_heapwalk. _HEAPOK is returned with the last block on the 
heap. _HEAPEND will be returned on the next call to _rtl_heapwalk. 

_rtl_heapwalk receives a pointer to a structure of type _HEAPINFO (declared 
in malloc.h). 
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_rtl_heapwalk 



Return value 



See also 



For the first call to _rtl_heapwalk, set the hi._pentry field to NULL. 
_rtl_heapwalk returns with hi.jpentry containing the address of the first 
block. 

hi._size holds the size of the block in bytes. 

hi.juseflag is a flag that is set to _USEDENTRY if the block is currently in 
use. If the block is free, hi.juseflag is set to _FREEENTRY. 

One of the following values: 

_HEAPBADNODE A corrupted heap block has been found 
_HEAPBADPTR The _pentry field does not point to a valid heap 

block 
_HEAPEMPTY No heap exists 

_HEAPEND The end of the heap has been reached 

_HEAPOK The _heapinfo block contains valid information 

about the next heap block 

Jieapchk, Jieapset 



_rtl_open 



fcntl.h, share.h, io.h 



Function 
Syntax 



Remarks 



Opens an existing file for reading or writing. 

int _rtl_open (const char *filename, int oflags); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 









_rtl_open opens the file specified by filename, then prepares it for reading or 
writing, as determined by the value of oflags. The file is always opened in 
binary mode. 

oflags uses the flags from the following two lists. Only one flag from the 
first list can be used (and one must be used); the remaining flags can be 
used in any logical combination. 

List 1 : Read/write flags 

0_RDONLY Open for reading. 
0_WRONLY Open for writing. 
0_RDWR Open for reading and writing. 

The following additional values can be included in oflags (using an OR 
operation): 
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These symbolic 
constants are defined 
in fcntl.h and share.h. 



List 2: Other access flags 



Return value 



See also 



rtl read 



O.NOINHERIT 
SH COMPAT 



The file is not passed to child programs. 

Allow other opens with SH_COMPAT. The call will 

fail if the file has already been opened in any other 

shared mode. 
SH_DENYRW Only the current handle can have access to the file. 
SH_DENWR Allow only reads from any other open to the file. 

SH_DENYRD Allow only writes from any other open to the file. 
SHJDENYNO Allow other shared opens to the file, but not other 

SH_COMPAT opens. 

Only one of the SH_DENYxx values can be included in a single _rtl_open. 
These file-sharing attributes are in addition to any locking performed on 
the files. 

The maximum number of simultaneously open files is defined by 
HANDLE.MAX. 

On successful completion, _rtl_open returns a nonnegative integer (the file 
handle). The file pointer, which marks the current position in the file, is set 
to the beginning of the file. 

On error, _rtl_open returns -1. The global variable errno is set to one of the 
following: 



EACCES 
EINVACC 
EMFILE 
ENOENT 



Permission denied 
Invalid access code 
Too many open files 
Path or file not found 



open, _rtl_read, sopen 



io.h, dos.h 



M 



Function 
Syntax 



Remarks 



Reads from file. 

int _rtl_read(int handle, void *buf, unsigned len) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 











_rtl_read attempts to read len bytes from the file associated with handle into 
the buffer pointed to by buf. 

When a file is opened in text mode, _rtl_read does not remove carriage 
returns. 
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Return value 



See also 



The argument handle is a file handle obtained from a creat, open, dup, or dup2 
call. 

On disk files _rtl_read begins reading at the current file pointer. When the 
reading is complete, the function increments the file pointer by the number 
of bytes read. On devices, the bytes are read directly from the device. 

The maximum number of bytes that _rtl_read can read is UINT_MAX -1, 
because UINT_MAX is the same as -1, the error return indicator. 
UINT_MAX is defined in limits.h. 

On successful completion, _rtl_read returns a positive integer indicating the 
number of bytes placed in the buffer. On end-of-file, _rtl_read returns zero. 
On error, it returns -1, and the global variable errno isset to one of the 
following values: 



EACCES 
EBADF 



Permission denied 
Bad file number 



read, _rtl_open, _rtl_write 



rtl write 



io.h 



Function 
Syntax 



Remarks 



Writes to a file. 

int _rtl_write(int handle, void *buf, unsigned len) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 









_rtl_write attempts to write len bytes from the buffer pointed to by buf to the 
file associated with handle. The maximum number of bytes that _rtl_write 
can write is UINTJVIAX -1, because UINTJVIAX is the same as -1, which is 
the error return indicator for _rtl_write. UINT_MAX is defined in limits.h. 
_rtl_write does not translate a linefeed character (LF) to a CR/LF pair 
because all its files are binary files. 

If the number of bytes actually written is less than that requested, the 
condition should be considered an error and probably indicates a full disk. 

For disk files, writing always proceeds from the current file pointer. On 
devices, bytes are directly sent to the device. 

For files opened with the 0_APPEND option, the file pointer is not 
positioned to EOF by _rtl_write before writing the data. 
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Return value 



See also 



_rtl_write returns the number of bytes written. In case of error, _rtl_write 
returns -1 and sets the global variable errno to one of the following values: 



EACCES 
EBADF 



Permission denied 
Bad file number 



Iseek, _rtl_read, write 



scanf 



stdio.h 



Function 
Syntax 



Remarks 



The format string 



Scans and formats input from the stdin stream. 

int scanf (const char * format [, address, ...]); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 




■ 


■ 


■ 


■ 



scanf scans a series of input fields, one character at a time, reading from the 
stdin stream. Then each field is formatted according to a format specifier 
passed to scanf in the format string pointed to by format. Finally, scanf stores 
the formatted input at an address passed to it as an argument following 
format. There must be the same number of format specifiers and addresses 
as there are input fields. 

For Win32s or Win32 GUI applications, stdin must be redirected. 

The format string present in scanf and the related functions cscanf, fscanf, 
sscanf, vscanf, vfscanf, and vsscanf controls how each function scans, 
converts, and stores its input fields. There must be enough address arguments 
for the given format specifiers; if not, the results will be unpredictable and possibly 
disastrous. Excess address arguments (more than required by the format) 
are ignored. 

scanf often leads to unexpected results if you diverge from an expected 
pattern. You need to remember to teach scanf how to synchronize at the end 
of a line. The combination of gets or fgets followed by sscanf is safe and easy, 
and therefore preferred. 

The format string is a character string that contains three types of objects: 
whitespace characters, non-whitespace characters, and format specifiers. 

■ The whitespace characters are blank, tab (\t) or newline (\n). If a . . .scanf 
function encounters a whitespace character in the format string, it will 
read, but not store, all consecutive whitespace characters up to the next 
non-whitespace character in the input. 
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Optional format 
string components 



■ The non-whitespace characters are all other ASCII characters except the 
percent sign (%). If a ...scanf function encounters a non-whitespace 
character in the format string, it will read, but not store, a matching non- 
whitespace character. 

■ The format specifiers direct the . . .scanf functions to read and convert 
characters from the input field into specific types of values, then store 
them in the locations given by the address arguments. 

Trailing whitespace is left unread (including a newline), unless explicitly 
matched in the format string. 

Format specifiers 

. . .scanf format specifiers have the following form: 

% [*] [width] [FIN] [hlllL] type_character 

Each format specifier begins with the percent character (%). After the % 
come the following, in this order: 

■ An optional assignment-suppression character, [ * ] 

■ An optional width specifier, [width] 

■ An optional pointer size modifier, [FIN] 

■ An optional argument-type modifier, [hlllL] 

■ The type character 

These are the general aspects of input formatting controlled by the optional 
characters and specifiers in the . . .scanf format string: 



Character 
or specifier 



width 



size 



argument 
type 



What it controls or specifies 



Suppresses assignment of the next input field. 

Maximum number of characters to read; fewer characters might be read if 
the ...sca/tffunction encounters a whitespace or unconvertible character. 

Overrides default size of address argument: 

A/= near pointer 
F= far pointer 

Overrides default type of address argument: 

h = short int 

/= long int (if the type character specifies an integer conversion) 
/= double (if the type character specifies a floating-point conversion) 
L = long double (valid only with floating-point conversions) 



220 



Library Reference 



scanf 



...scanf type The following table lists the . . .scanf type characters, the type of input 
characters expected by each, and in what format the input will be stored. 

The information in this table is based on the assumption that no optional 
characters, specifiers, or modifiers (*, width, or size) were included in the 
format specifier. 

To see how the addition of the optional elements affects the ...scanf input, 
refer to the tables following this one. 



Type 
character 



Expected input 



Type of argument 



Numerics 

d 
D 

o 




u 
U 

x 
X 

e,E 

f 

g,G 

Characters 
s 
c 



Decimal integer 
Decimal integer 

Octal integer 
Octal integer 

Decimal, octal, or 
hexadecimal integer 
Decimal, octal, or 
hexadecimal integer 

Unsigned decimal 
integer 

Unsigned decimal 
integer 

Hexadecimal integer 
Hexadecimal integer 

Floating point 

Floating point 

Floating point 



Character string 
Character 



% character 



Pointer to int (int *arg). 
Pointer to long (long *arg). 

Pointer to int (int *arg). 
Pointer to long (long *arg). 

Pointer to int (int *arg). 
Pointer to long (long *arg). 

Pointer to unsigned int (unsigned int *arg). 
Pointer to unsigned long (unsigned long *arg). 

Pointer to int (int *arg). 
Pointer to int (int *arg). 

Pointer to float (float *arg). 

Pointer to float (float *arg). 

Pointer to float (float *arg). 

Pointer to array of characters (char arg[]). 

Pointer to character (char *arg) if a field width W is given along with the c- 
type character (such as %5c). 

Pointer to array of W characters (char arg[W\). 

No conversion done; % is stored. 
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Type 
character 



Expected input 



Type of argument 



Pointers 
n 



Pointer to int (int *arg). The number of characters read successfully up to %n 
is stored in this int. 

Hexadecimal form Pointer to an object, (far* or near*) 

YYYY:ZZZZ or %p conversions default to the 

ZZZZ pointer size native to the memory model. 



Input fields Any one of the following is an input field: 

■ All characters up to (but not including) the next whitespace character 

■ All characters up to the first one that cannot be converted under the 
current format specifier (such as an 8 or 9 under octal format) 

■ Up to n characters, where n is the specified field width 

Conventions Certain conventions accompany some of these format specifiers. The 

decimal-point character used in the output is determined by the current 
locale's LC_NUMERIC category. The conventions are summarized here. 

%c conversion 

This specification reads the next character, including a whitespace charac- 
ter. To skip one whitespace character and read the next non-whitespace 
character, use %ls. 

%Wc conversion (W = width specification) 

The address argument is a pointer to an array of characters; the array 
consists of W elements (char arg[W\). 

%s conversion 

The address argument is a pointer to an array of characters (char flrg[]). 

The array size must be at least (n+1) bytes, where n equals the length of 
string s (in characters). A space or newline terminates the input field; the 
terminator is not scanned or stored. A null-terminator is automatically 
appended to the string and stored as the last element in the array. 

%[search_set] conversion 

The set of characters surrounded by square brackets can be substituted for 
the s-type character. The address argument is a pointer to an array of 
characters (char flrg[]). 

These square brackets surround a set of characters that define a search set of 
possible characters making up the string (the input field). 
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If the first character in the brackets is a caret ( A ), the search set is inverted to 
include all ASCII characters except those between the square brackets. 
(Normally, a caret will be included in the inverted search set unless 
explicitly listed somewhere after the first caret.) 

The input field is a string not delimited by whitespace. ...scanf reads the 
corresponding input field up to the first character it reaches that does not 
appear in the search set (or in the inverted search set). Two examples of this 
type of conversion are 

% [abed] Searches for any of the characters a, b, c, and d in the input 

field. 
% [ A abcd] Searches for any characters except a, b, c, and d in the input 

field. 

You can also use a range facility shortcut to define a range of characters 
(numerals or letters) in the search set. For example, to catch all decimal 
digits, you could define the search set by using % [0123456789], or you could 
use the shortcut to define the same search set by using % [0-9 ] . 

To catch alphanumeric characters, use the following shortcuts: 

I [A-Z] Catches all uppercase letters. 

% [ - 9 A- Za- z ] Catches all decimal digits and all letters (uppercase and 

lowercase). 
% [A-FT-Z] Catches all uppercase letters from A through F and from 

T through Z. 

The rules covering these search set ranges are straightforward: 

■ The character prior to the hyphen (-) must be lexically less than the one 
after it. 

■ The hyphen must not be the first nor the last character in the set. (If it is 
first or last, it is considered to be the hyphen character, not a range 
definer.) 

■ The characters on either side of the hyphen must be the ends of the range 
and not part of some other range. 

Here are some examples where the hyphen just means the hyphen 
character, not a range between two ends: 

%[-+*/] The four arithmetic operations. 

% [ z - a ] The characters z, -, and a . 

% [+0-9-A-Z] The characters + and - and the ranges 0-9 and A-Z. 
% [ + - 9 A- Z - ] Also the characters + and - and the ranges 0-9 and A-Z. 
% [ A -0-9+A-z] All characters except + and - and those in the ranges 0-9 
and A-Z. 
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JF = INFinity; NAN = 

Not-A-Number 



Assignment- 
suppression 
character 



%e, %E. %f, %g, and %G (floating-point) conversions 

Floating-point numbers in the input field must conform to the following 
generic format: 

[+/-] ddddddddd [.] dddd [E I e] [+/-] ddd 

where [item] indicates that item is optional, and ddd represents decimal, 
octal, or hexadecimal digits. 

In addition, +INF, -INF, +NAN, and -NAN are recognized as floating- 
point numbers. Note that the sign and capitalization are required. 

%d, %i, %o, %x, %D, %l, %0, %X, %c, %n conversions 

A pointer to unsigned character, unsigned integer, or unsigned long can be 

used in any conversion where a pointer to a character, integer, or long is 

allowed. 

The assignment-suppression character is an asterisk (*); it is not to be 
confused with the C indirection (pointer) operator (also an asterisk). 

If the asterisk follows the percent sign (%) in a format specifier, the next 
input field will be scanned but not assigned to the next address argument. 
The suppressed input data is assumed to be of the type specified by the 
type character that follows the asterisk character. 

The success of literal matches and suppressed assignments is not directly 
determinable. 

Width specifiers The width specifier (n), a decimal integer, controls the maximum number of 
characters that will be read from the current input field. 

If the input field contains fewer than n characters, . . .scanf reads all the 
characters in the field, then proceeds with the next field and format 
specifier. 

If a whitespace or nonconvertible character occurs before width characters 
are read, the characters up to that character are read, converted, and stored, 
then the function attends to the next format specifier. 

A nonconvertible character is one that cannot be converted according to the 
given format (such as an 8 or 9 when the format is octal, or a J or K when 
the format is hexadecimal or decimal). 



Width 
specifier 



How width of stored input is affected 



Up to n characters are read, converted, and stored in the current address 
argument. 
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Input-size and 

argument-type 

modifiers 



The input-size modifiers (N and F) and argument-type modifiers (h, I, and 
L) affect how the . . .scanf functions interpret the corresponding address 
argument arg[f]. 

F and N override the default or declared size of arg. 

h, I, and L indicate which type (version) of the following input data is to be 
used (h = short, / = long, L = long double). The input data will be converted 
to the specified version, and the arg for that input data should point to an 
object of the corresponding size (short object for %h, long or double object 
for %l, and long double object for %L). 



Modifier 



How conversion is affected 



When scanf stops 
scanning 



F Overrides default or declared size; arg interpreted as far pointer. 

N Overrides default or declared size; arg interpreted as near pointer. Cannot be 

used with any conversion in huge model. 

h For d, /', o, u, x types, convert input to short int, store in short object. 

For D, /, 0, U, X types, no effect. 

For e, f, c, s, n, p types, no effect. 
1 Ford, ;', o, u, xtypes, convert input to long int, store in long object. 

For e, f, g types, convert input to double, store in double object. 

For D, /, 0, U, X types, no effect. 

For c, s, n, p types, no effect. 

L For e, f, g types, convert input to a long double, store in long double object. L 

has no effect on other formats. 

scanf might stop scanning a particular field before reaching the normal 
field-end character (whitespace), or might terminate entirely, for a variety 
of reasons. 

scanf stops scanning and storing the current field and proceed to the next 
input field if any of the following occurs: 

■ An assignment-suppression character (*) appears after the percent 
character in the format specifier; the current input field is scanned but 
not stored. 

■ width characters have been read (width = width specification, a positive 
decimal integer in the format specifier). 

■ The next character read cannot be converted under the current format 
(for example, an A when the format is decimal). 
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Return value 



See also 



■ The next character in the input field does not appear in the search set (or 
does appear in an inverted search set). 

When scanf stops scanning the current input field for one of these reasons, 
the next character is assumed to be unread and to be the first character of 
the following input field, or the first character in a subsequent read 
operation on the input. 

scanf will terminate under the following circumstances: 

■ The next character in the input field conflicts with a corresponding non- 
whitespace character in the format string. 

■ The next character in the input field is EOF. 

■ The format string has been exhausted. 

If a character sequence that is not part of a format specifier occurs in the 
format string, it must match the current sequence of characters in the input 
field; scanf will scan but not store the matched characters. When a 
conflicting character occurs, it remains in the input field as if it were never 
read. 

scanf returns the number of input fields successfully scanned, converted, 
and stored; the return value does not include scanned fields that were not 
stored. If scanf attempts to read at end-of-file, the return value is EOF. If no 
fields were stored, the return value is 0. 

atof, cscanf, fscanf, freopen, getc, printf, sscanf, vfscanf, vscanf, vsscanf 



searchenv 



stdlib.h 



Function 
Syntax 



Searches an environment path for a file. 

void _searchenv (const char *file, const char *varname, char *buf), 



Remarks 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 






■ 



_searchenv attempts to locate file, searching along the path specified by the 
operating system environment variable varname. Typical environment 
variables that contain paths are PATH, LIB, and INCLUDE. 

_searchenv searches for the file in the current directory of the current drive 
first. If the file is not found there, the environment variable varname is 
fetched, and each directory in the path it specifies is searched in turn until 
the file is found, or the path is exhausted. 
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Return value 
See also 



When the file is located, the full path name is stored in the buffer pointed to 
by buf. This string can be used in a call to access the file (for example, with 
fopen or exec. ..). The buffer is assumed to be large enough to store any 
possible file name. If the file cannot be successfully located, an empty string 
(consisting of only a null character) will be stored at buf. 

None. 

_dos_find first, _dos_findnext, exec. . ., spawn.. ., system 



searchpath 



dir.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Searches the operating system path for a file. 

char * searchpath (const char *file); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


" 






■ 



searchpath attempts to locate file, searching along the operating system path, 
which is the PATH=... string in the environment. A pointer to the complete 
path-name string is returned as the function value. 

searchpath searches for the file in the current directory of the current drive 
first. If the file is not found there, the PATH environment variable is 
fetched, and each directory in the path is searched in turn until the file is 
found, or the path is exhausted. 

When the file is located, a string is returned containing the full path name. 
This string can be used in a call to access the file (for example, with fopen or 
exec...). 

The string returned is located in a static buffer and is overwritten on each 
subsequent call to searchpath. 

searchpath returns a pointer to a file name string if the file is successfully 
located; otherwise, searchpath returns null. 

exec. . ., findfirst, findnext, spawn.. ., system 



I 



searchstr 



stdlib.h 



Function 
Syntax 



Searches a list of directories for a file. 

void _searchstr( const char *file, const char *ipath, char *buf); 
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Remarks 



Return value 
See also 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 






■ 



_searchstr attempt to locate file, searching along the path specified by the 
string ipath. 

_searchstr searches for the file in the current directory of the current drive 
first. If the file is not found there, each directory in ipath is searched in turn 
until the file is found, or the path is exhausted. The directories in ipath must 
be separated by semicolons. 

When the file is located, the full path name is stored in the buffer pointed 
by by buf. This string can be used in a call to access the file (for example, 
with f open or exec. . .). The buffer is assumed to be large enough to store any 
possible file name. The constant _MAX_PATH, defined in stdlib.h, is the 
size of the largest file name. If the file cannot be successfully located, an 
empty string (consisting of only a null character) will be stored at buf. 

None. 

searchenv 



segread 



dos.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Reads segment registers. 

void segread (struct SREGS *segp) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 











segread places the current values of the segment registers into the structure 
pointed to by segp. 

This call is intended for use with intdosx and int86x. 

None. 

FPjOFF, int86, int86x, intdos, intdosx, MKJFP, movedata 



setbuf 



stdio.h 



Function 
Syntax 



Assigns buffering to a stream. 

void setbuf (FILE *stream, char *buf); 
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Remarks 



Return value 
See also 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 



setbuf causes the buffer buf to be used for I/O buffering instead of an 
automatically allocated buffer. It is used after stream has been opened. 

If buf is null, I/O will be unbuffered; otherwise, it will be fully buffered. 
The buffer must be BUFSIZ bytes long (specified in stdio.h). 

stdin and stdout are unbuffered if they are not redirected; otherwise, they 
are fully buffered, setbuf can be used to change the buffering style used. 

Unbuffered means that characters written to a stream are immediately 
output to the file or device, while buffered means that the characters are 
accumulated and written as a block. 

setbuf produces unpredictable results unless it is called immediately after 
opening stream or after a call to fseek. Calling setbuf after stream has been 
unbuffered is legal and will not cause problems. 

A common cause for error is to allocate the buffer as an automatic (local) 
variable and then fail to close the file before returning from the function 
where the buffer was declared. 

None. 

fflush, fopen, fseek, setvbuf 



setcbrk 



dos.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Sets control-break setting. 

int setcbrk(int cbrkvalue) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 











I 



setcbrk uses the DOS system call 0x33 to turn control-break checking on or 
off. 

cbrkvalue = Turns checking off (check only during I/O to console, 
printer, or communications devices). 

cbrkvalue = 1 Turns checking on (check at every system call). 

setcbrk returns cbrkvalue, the value passed. 

getcbrk 
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_setcursortype 



conio.h 



Function 
Syntax 



Remarks 



Return value 



Selects cursor appearance. 

void _setcursortype(int cur_t); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 






■ 






■ 



Sets the cursor type to 

_NOCURSOR Turns off the cursor 

_NORMALCURSOR Normal underscore cursor 
_SOLIDCURSOR Solid block cursor 

This function should not be used in Win32s or Win32 GUI applications. 

None. 



setdate 



setdisk 



See _dos_getdate. 



See getdisk. 



setdta 



dos.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Sets disk-transfer address. 

void setdta (char far *dta); 
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setdta changes the current setting of the DOS disk-transfer address (DTA) to 
the value given by dta. 

None. 

getdta 
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setftime 



See getftime. 



setjmp 

Function 
Syntax 



Remarks 



setjmp.h 



Sets up for nonlocal goto. 

int setjmp (jmp_buf jmpb); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ i 


" 


■ 


■ 


■ 


■ 



setjmp captures the complete task state in jmpb and returns 0. 

A later call to longjmp with jmpb restores the captured task state and returns 
in such a way that setjmp appears to have returned with the value val. 

A task state includes: 



Win 16 



Win32 



Return value 
See also 



All segment registers 
CS, DS, ES, SS 

Register variables 
DlandSI 

Stack pointer SP 

Frame pointer BP 

Flags 



No segment registers 
are saved 

Register variables 
EBX, EDI, ESI 

Stack pointer ESP 

Frame pointer EBP 

Flags are not saved 



A task state is complete enough that setjmp can be used to implement 
coroutines. 

setjmp must be called before longjmp. The routine that calls setjmp and sets 
up jmpb must still be active and cannot have returned before the longjmp is 
called. If it has returned, the results are unpredictable. 

setjmp is useful for dealing with errors and exceptions encountered in a 
low-level subroutine of a program. 

setjmp returns when it is initially called. If the return is from a call to 
longjmp, setjmp returns a nonzero value (as in the example). 

longjmp, signal 
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setlocale 



setlocale 



locale.h 



Function 
Syntax 



Remarks 



Future releases of 

Borland C++ will 

increase the number 

of locales supported. 



Selects or queries a locale. 

char *setlocale(int category, const char *locale); 
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Borland C++- supports the following locales at present: 

Module Locale supported 

de_DE German 

fr_FR French 

en_GB English (Great Britain) 

enJJS English (United States) 

For each locale, the following character sets are supported: 

DOS437 English 

DOS850 Multilingual (Latin I) 

WIN1252 Windows, Multilingual 

For a description of DOS character sets, see MS-DOS User's Guide and 
Reference. See also MS Windows 3.1 Programmer's Reference, Volume 4 for a 
discussion of the WIN1252 character set. 

The possible values for the category argument are as follows: 



Value 



Description 



LC.ALL 

LC.COLLATE 

LC_CTYPE 

LC.MONETARY 
LC_NUMERIC 

LC TIME 



Affects all the following categories. 

Affects strcoll and strxfrm. 

Affects single-byte character handling functions. The mbstowcs and mbtowc 
functions are not affected. 

Affects monetary formatting by the localeconv function. 

Affects the decimal point of non-monetary data formatting. This includes the 
printf family of functions, and the information returned by localeconv. 

Affects strftime. 



The locale argument is a pointer to the name of the locale or named locale 
category. Passing a NULL pointer returns the current locale in effect. 
Passing a pointer that points to a null string requests setlocale to look for 
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The LOCALE.BLL file 

is installed in BC4\ 

BIN directory. 



See the 

Programmers Guide, 

Chapter 5, for 

information about 

defining options. 



environment variables to determine which locale to set. The locale names 
are case sensitive. 

If you specify a locale other than the default C locale, setlocale tries to access 
the locale library file named LOCALE.BLL to obtain the locale data. This 
file is located using the following strategies: 

1. Searching the directory where the application's executable resides. 

2. Searching in the current default directory. 

3. Accessing the "PATH" environment variable and searching in each of 
the specified directories. 

If the locale library is not found, setlocale terminates. 

When setlocale is unable to honor a locale request, the preexisting locale in 
effect is unchanged and a null pointer is returned. 

If the locale argument is a NULL pointer, the locale string for the category is 
returned. If category is LC_ALL, a complete locale string is returned. The 
structure of the complete locale string consists of the names of all the 
categories in the current locale concatenated and separated by semicolons. 
This string can be used as the locale parameter when calling setlocale with 
LC_ALL. This will reinstate all the locale categories that are named in the 
complete locale string, and allows saving and restoring of locale states. If 
the complete locale string is used with a single category, for example, 
LC_TIME, only that category will be restored from the locale string. 

ANSI C states that if an empty string "" is used as the locale parameter an 
implementation defined locale is used, setlocale has been implemented to 
look for corresponding environment variables in this instance as POSIX 
suggests. 

If the environment variable LC_ALL exists, the category will be set 
according to this variable. If the variable does not exist, the environment 
variable that has the same name as the requested category is looked for and 
the category is set accordingly. 

If none of the above are satisfied, the environment variable named LANG is 
used. Otherwise, setlocale fails and returns a NULL pointer. 

To take advantage of dynamically loadable locales in your application, 

define _ _USELOCALES for each module. If USELOCALES is not 

defined, all locale-sensitive functions and macros will work only with the 
default C locale. 

If a NULL pointer is used as the argument for the locale parameter, setlocale 
returns a string that specifies the current locale in effect. If the category 
parameter specifies a single category, such as LC_COLLATE, the string 
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setlocale 



pointed to will be the name of that category. If LC_ALL is used as the 
category parameter then the string pointed to will be a full locale string that 
will indicate the name of each category in effect. 



localenameptr = setlocale ( LC_COLLATE, NULL 



if (localenameptr) 
printf( "ls\n" 



localenameptr 



The default collation 

is named dbase. 

Therefore, whether 

you specify dbase or 

nothing at all, you get 

the same collation. 

However, dbase 

might not be the 

default in future 

releases. 



The output here will be one of the module names together with the 
specified code page. For example, the output could be fr_FR.DOS850@dbase. 

localenameptr = setlocale ( LC_ALL, NULL ); 

if (localenameptr) 

printf( "%s\n", localenameptr ); 

An example of the output here could be the following: 

fr_FR.DOS850@dbase;fr_FR.DOS850;fr_FR.DOS850;fr_FR.DOS850; 
f r_FR . D0S8 5 ; f r_FR . D0S8 5 ; ; 

Each category in this full string is delimited by a semicolon. This string can 
be copied and saved by an application and then used again to restore the 
same locale categories at another time. Each delimited name corresponds to 
the locale category constants defined in locale.h. Therefore, the first name is 
the name of the LC_COLLATE category, the second is the LC_CTYPE 
category, and so on. Any other categories named in the locale.h header file 
are reserved for future implementation. 

Here are some examples of setting locales by using setlocale: 

Set all default categories for the specified French locale: 

setlocale( LC_ALL, "fr_FR.DOS850" ); 

Set French locale to named collation dbase: 

setlocale ( LC_COLLATE, "fr_FR.DOS850@dbase" ') 

When a category is loaded from the locale library, the default category is 
the one that will be loaded unless a modifier name is used. For example: 

setlocale( LC_COLLATE, "fr_FR.DOS850" ) 

causes the default LC_COLLATE category to be loaded. It might or might 
not have a specific name. 

setlocale( LC_COLLATE, "fr_FR.DOS850@dbase" ) 
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Return value 



See also 



specifies that the LC_COLLATE category named dbase to be loaded. This 
might or might not be the default. 

setlocale updates the Iconv locale structure when a request has been fulfilled. 

When an application exits, any allocated memory used for the locale object 
is deallocated. 

If selection is successful, setlocale returns a pointer to a string that is associ- 
ated with the selected category (or possibly all categories) for the new 
locale. 

On failure, a NULL pointer is returned and the locale is unchanged. All 
other possible returns are discussed in the Remarks section above. 

localeconv 



setmem 



mem.h 



Function 
Syntax 



Remarks 
Return value 
See also 



Assigns a value to a range of memory. 

void setmem (void *dest, unsigned length, char value); 
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setmem sets a block of length bytes, pointed to by dest, to the byte value. 

None. 

memset, strset 



setmode 



fcntl.h 




Function 
Syntax 



Remarks 



Sets mode of an open file. 

int setmode (int handle, int amode) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 






" 



setmode sets the mode of the open file associated with handle to either binary 
or text. The argument amode must have a value of either OJ3INARY or 
0_TEXT, never both. (These symbolic constants are defined in fcntl.h.) 
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Return value 



See also 



setmode returns the previous translation mode if successful. On error it 
returns -1 and sets the global variable errno to 

EINVAL Invalid argument 

_rtl_creat, creat, _rtl_open, open 



settime 



See gettime on page 133. 



setvbuf 



stdio.h 



Function 
Syntax 



Remarks 



Assigns buffering to a stream. 

int setvbuf (FILE *stream, char *buf, int type, size_t size) 
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setvbuf causes the buffer buf to be used for I/O buffering instead of an 
automatically allocated buffer. It is used after the given stream is opened. 

If buf is null, a buffer will be allocated using malloc; the buffer will use size 
as the amount allocated. The buffer will be automatically freed on close. 
The size parameter specifies the buffer size and must be greater than zero. 

The parameter size is limited by the constant UINT_MAX as defined in 
limits.h. 

stdin and stdout are unbuffered if they are not redirected; otherwise, they 
are fully buffered. Unbuffered means that characters written to a stream are 
immediately output to the file or device, while buffered means that the 
characters are accumulated and written as a block. 

The type parameter is one of the following: 

■ _IOFBF The file is fully buffered. When a buffer is empty, the next 

input operation will attempt to fill the entire buffer. On 
output, the buffer will be completely filled before any data is 
written to the file. 

■ _IOLBF The file is line buffered. When a buffer is empty, the next input 

operation will still attempt to fill the entire buffer. On output, 
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Return value 
See also 



however, the buffer will be flushed whenever a newline 
character is written to the file. 

■ _IONBF The file is unbuffered. The buf and size parameters are 

ignored. Each input operation will read directly from the 
file, and each output operation will immediately write the 
data to the file. 

A common cause for error is to allocate the buffer as an automatic (local) 
variable and then fail to close the file before returning from the function 
where the buffer was declared. 

setvbuf returns on success. It returns nonzero if an invalid value is given 
for type or size, or if there is not enough space to allocate a buffer. 

fflush, fopen, setbuf 



setvect 



See getvect. 



setverify 



dos.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Sets the state of the verify flag in the operating system. 

void setverify(int value); 
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setverify sets the current state of the verify flag to value, which can be either 
(off) or 1 (on). 

The verify flag controls output to the disk. When verify is off, writes are not 
verified; when verify is on, all disk writes are verified to ensure proper 
writing of the data. 

None. 

getverify 




signal 



signal.h 



Function 



Specifies signal-handling actions. 
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Syntax 



Remarks 



void (JJSERENTRY *signal(int sig, void (JJSERENTRY *func) 

(int sig[, int subcode] ))) (int) 
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signal determines how receipt of signal number sig will subsequently be 
treated. You can install a user-specified handler routine (specified by the 
argument fund) or use one of the two predefined handlers, SIG_DFL and 
SIG_IGN, in signal.h. The function func must be used with the 
JJSERENTRY calling convention. 



Function pointer 



Description 



SIG.DFL 
SIG.ERR 
SIG IGN 



Terminates the program 
Indicates an error return from signal 
Ignore this type signal 



The signal types and their defaults are as follows: 



Signal type 



Description 




SIGBREAK Keyboard must be in raw mode. 

SIGABRT Abnormal termination. Default action is equivalent to calling 

_exit(3). 

SIGFPE Arithmetic error caused by division by 0, invalid operation, and 

the like. Default action is equivalent to calling _ex/7(1 ). 

SIGILL Illegal operation. Default action is equivalent to calling 

SIGINT Ctrl-C interrupt. Default action is to do an INT 23h. 

SIGSEGV Illegal storage access. Default action is equivalent to calling 

_exfl(1). 

SIGTERM Request for program termination. Default action is equivalent to 

calling _exit{\). 

SIGUSR1 , User-defined signals that can be generated only 

SIGUSR2, by calling raise. Default action is to ignore 

SIGUSR3 the signal. 

signal.h defines a type called sig_atomic_t, the largest integer type the 
processor can load or store atomically in the presence of asynchronous 
interrupts (for the 8086 family, this is a 16-bit word; for 80386 and higher 
number processors, it is a 32-bit word — a Borland C++ integer). 

When a signal is generated by the raise function or by an external event, the 
following two things happen: 
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■ If a user-specified handler has been installed for the signal, the action for 
that signal type is set to SIGJDFL. 

■ The user-specified function is called with the signal type as the 
parameter. 

User-specified handler functions can terminate by a return or by a call to 
abort, _exit, exit, or longjmp. If your handler function is expected to continue 
to receive and handle more signals, you must have the handler function call 
signal again. 

Borland C++ implements an extension to ANSI C when the signal type is 
SIGFPE, SIGSEGV, or SIGILL. The user-specified handler function is called 
with one or two extra parameters. If SIGFPE, SIGSEGV, or SIGILL has been 
raised as the result of an explicit call to the raise function, the user-specified 
handler is called with one extra parameter, an integer specifying that the 
handler is being explicitly invoked. The explicit activation values for 
SIGFPE, SIGSEGV and SIGILL are as follows (see declarations in float.h): 

Signal Meaning 

SIGFPE FPE.EXPLICITGEN 

SIGSEGV SEGV_EXPLICITGEN 
SIGILL ILL.EXPUCITGEN 

If SIGFPE is raised because of a floating-point exception, the user handler is 
called with one extra parameter that specifies the FPE_xxx type of the 
signal. If SIGSEGV, SIGILL, or the integer-related variants of SIGFPE 
signals (FPEJNTOVFLOW or FPEJNTDIVO) are raised as the result of a 
processor exception, the user handler is called with two extra parameters: 

1. The SIGFPE, SIGSEGV, or SIGILL exception type (see float.h for all 
these types). This first parameter is the usual ANSI signal type. 

2. An integer pointer into the stack of the interrupt handler that called the 
user-specified handler. This pointer points to a list of the processor 
registers saved when the exception occurred. The registers are in the 
same order as the parameters to an interrupt function; that is, BP, DI, SI, 
DS, ES, DX, CX, BX, AX, IP, CS, FLAGS. To have a register value 
changed when the handler returns, change one of the locations in this 
list. For example, to have a new SI value on return, do something like 
this: 

*( (int*)list_pointer + 2) = new_SI_value; 
In this way, the handler can examine and make any adjustments to the 
registers that you want. 
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The following SIGFPE-type signals can occur (or be generated). They 
correspond to the exceptions that the 8087 family is capable of detecting, as 
well as the "INTEGER DIVIDE BY ZERO" and the "INTERRUPT ON 
OVERFLOW" on the main CPU. (The declarations for these are in float.h.) 

SIGFPE signal Meaning 

FPEJNTOVFLOW INTO executed with OF flag set 

FPEJNTDIVO Integer divide by zero 

FPEJNVALID Invalid operation 

FPE_ZERODIVIDE Division by zero 

FPEJDVERFLOW Numeric overflow 

FPEJJNDERFLOW Numeric underflow 

FPEJNEXACT Precision 

FPE_EXPLICITGEN User program executed ra/se(SIGFPE) 

FPE_STACKFAULT Floating-point stack overflow or underflow 

The FPEJNTOVFLOW and FPEJNTDIVO signals are generated by integer 
operations, and the others are generated by floating-point operations. 
Whether the floating-point exceptions are generated depends on the 
coprocessor control word, which can be modified with _control87. 
Denormal exceptions are handled by Borland C++ and not passed to a 
signal handler. 

The following SIGSEGV-type signals can occur: 

SEGVJ30UND Bound constraint exception 

SEGV_EXPLICITGEN rafse(SIGSEGV) was executed 

The 8088 and 8086 processors don't have a bound instruction. The 186, 286, 
386, and NEC V series processors do have this instruction. So, on the 8088 
and 8086 processors, the SEGV_BOUND type of SIGSEGV signal won't 
occur. Borland C++ doesn't generate bound instructions, but they can be 
used in inline code and separately compiled assembler routines that are 
linked in. 

The following SIGILL-type signals can occur: 

ILL_EXECUTION Illegal operation attempted 

ILL_EXPLICITGEN raz'se(SIGILL) was executed 

The 8088, 8086, NEC V20, and NEC V30 processors don't have an illegal 
operation exception. The 186, 286, 386, NEC V40, and NEC V50 processors 
do have this exception type. So, on 8088, 8086, NEC V20, and NEC V30 
processors, the ILL JiXECUTION type of SIGILL won't occur. 

When the signal type is SIGFPE, SIGSEGV, or SIGILL, a return from a 
signal handler is generally not advisable if the state of the 8087 is corrupt, 
the results of an integer division are wrong, an operation that shouldn't 
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Return value 



See also 



have overflowed did, a bound instruction failed, or an illegal operation was 
attempted. The only time a return is reasonable is when the handler alters 
the registers so that a reasonable return context exists or the signal type in- 
dicates that the signal was generated explicitly (for example, 
FPE_EXPLICITGEN, SEGV_EXPLICITGEN, or ILL_EXPLICITGEN). 
Generally in this case you would print an error message and terminate the 
program using _exit, exit, or abort. If a return is executed under any other 
conditions, the program's action will probably be unpredictable upon 
resuming. 

If the call succeeds, signal returns a pointer to the previous handler routine 
for the specified signal type. If the call fails, signal returns SIG_ERR, and the 
external variable errno is set to EINVAL. 

abort, _control87, ctrlbrk, exit, longjmp, raise, setjmp 



sin, sinl 



math.h 



Function 
Syntax 



Remarks 



Return value 
See also 



sin 



sinl 



Calculates sine. 

double sinfdouble x) ; 

long double sinl (long double x) ; 
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sin computes the sine of the input value. Angles are specified in radians. 

sinl is the long double version; it takes a long double argument and returns 
a long double result. Error handling for these functions can be modified 
through the functions jnatherr and jnatherrl. 

This function can be used with bed and complex types. 

sin and sinl return the sine of the input value. 

acos, asin, atan, atanl, bed, complex, cos, tan 




sinh, sinhl 



math.h 



Function 



Calculates hyperbolic sine. 
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sinh, sinhl 



Syntax 



Remarks 



sinh 
sinhl 



Return value 



See also 



double sinh (double x) ; 

long double sinhl (long double x) 
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sinh computes the hyperbolic sine, (e x - e" x )/2. 

sinl is the long double version; it takes a long double argument and returns 
a long double result. Error handling for sinh and sinhl can be modified 
through the functions jnatherr and jnatherrl. 

This function can be used with bed and complex types. 

sinh and sinhl return the hyperbolic sine of x. 

When the correct value overflows, these functions return the value 
HUGE_VAL (sinh) or _LHUGE_VAL (sinhl) of appropriate sign. Also, the 
global variable errno is set to ERANGE. 

acos, asin, atan, atanl, bed, complex, cos, cosh, sin, tan, tanh 



sleep 



dos.h 



Function 
Syntax 



Remarks 



Return value 



Suspends execution for an interval (seconds). 

void sleep (unsigned seconds); 
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With a call to sleep, the current program is suspended from execution for 
the number of seconds specified by the argument seconds. The interval is 
accurate only to the nearest hundredth of a second or to the accuracy of the 
operating system clock, whichever is less accurate. 

None. 



sopen 



fcntl.h, sys\stat.h, share.h, io.h 



Function 
Syntax 



Opens a shared file. 

int sopen(char *path, int access, int shflag[, int mode]); 



242 



Library Reference 



sopen 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 






■ 



Remarks 



sopen opens the file given by path and prepares it for shared reading or 
writing, as determined by access, shflag, and mode. 

For sopen, access is constructed by ORing flags bitwise from the following 
two lists. Only one flag from the first list can be used; the remaining flags 
can be used in any logical combination. 

List 1 : Read/write flags 

0_RDONLY Open for reading only. 

O.WRONLY Open for writing only. 

0_RDWR Open for reading and writing. 

List 2: Other access flags 

0_NDELAY Not used; for UNIX compatibility. 

0_APPEND If set, the file pointer is set to the end of the file prior 

to each write. 
0_CREAT If the file exists, this flag has no effect. If the file does 

not exist, the file is created, and the bits of mode are 

used to set the file attribute bits as in chmod. 
0_TRUNC If the file exists, its length is truncated to 0. The file 

attributes remain unchanged. 
O.EXCL Used only with O.CREAT. If the file already exists, 

an error is returned. 
0_BINARY This flag can be given to explicitly open the file in 

binary mode. 
0_TEXT This flag can be given to explicitly open the file in 

text mode. 
0_NOINHERIT The file is not passed to child programs. 

These 0_. . . symbolic constants are defined in fcntl.h. 

If neither 0_BINARY nor 0_TEXT is given, the file is opened in the transla- 
tion mode set by the global variable Jmode. 

If the 0_CREAT flag is used in constructing access, you need to supply the 
mode argument to sopen from the following symbolic constants defined in 
sys\stat.h. 




Value of mode 



Access permission 



SJWRITE 

SJREAD 

S IREADIS IWRITE 



Permission to write 
Permission to read 
Permission to read/write 



Chapter 3, Run-time functions 



243 



sopen 



shflag specifies the type of file-sharing allowed on the file path. Symbolic 
constants for shflag are defined in share.h. 



Value of shflag 



What it does 



Return value 



See also 



SH_COMPAT 

SH_DENYRW 

SH_DENYWR 

SH_DENYRD 

SH_DENYNONE 

SH DENYNO 



Sets compatibility mode. 
Denies read/write access. 
Denies write access. 
Denies read access. 
Permits read/write access. 
Permits read/write access. 



On successful completion, sopen returns a nonnegative integer (the file 
handle), and the file pointer (that marks the current position in the file) is 
set to the beginning of the file. On error, it returns -1, and the global 
variable errno is set to 

EACCES Permission denied 

EINVACC Invalid access code 

EMFILE Too many open files 

ENOENT Path or file function not found 

chmod, close, creat, lock, Iseek, _rtl_open, open, unlock, umask 



spawnl, spawnle, spawnlp, spawnlpe, spawnv, spawnve, spawnvp, 
spawnvpe process.h, stdio.h 



Function 
Syntax 



The last string must 

be NULL in functions 

spawnle, spawnlpe, 

spawnv, spawnve, 

spawnvp, and 

spawnvpe. 



Remarks 



Creates and runs child processes. 

int spawnl (int mode, char *path, char *argO, argl, . 
int spawnle (int mode, char *path, char *argO, argl, 
int spawnlp (int mode, char *path, char *argO, argl, 
int spawnlpe(int mode, char *path, char *argO, argl, 

char *envp[] ) ; 
int spawnvfint mode, char *path, char *argv[]); 
int spawnve (int mode, char *path, char *argv[], 
int spawnvpfint mode, char *path, char *argv[]) 
int spawnvpe (int mode, char *path, char 



argn, NULL); 

, argn, NULL, char *envp[ 
, argn, NULL) ; 
. , argn, NULL, 



argv[ 



char *envp[] ] 
char *envp[; 
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The functions in the spawn.. . family create child processes that run 
(execute) their own files. There must be sufficient memory available for 
loading and executing a child process. 
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spawnl, spawnle, spawnlp, spawnlpe, spawnv, spawnve, spawnvp, spawnvpe 



The value of mode determines what action the calling function (the parent 
process) takes after the spawn.. . call. The possible values of mode are 

P_WAIT Puts parent process "on hold" until child process 

completes execution. 

P_NOWAIT Continues to run parent process while child process 

runs. The child process ID is returned, so that the 
parent can wait for completion using cwait or wait. 

P_NOWAITO Identical to P_NOWAIT except that the child process 
ID isn't saved by the operating system, so the parent 
process can't wait for it using cwait or wait. 

P_DETACH Identical to P_NOWAITO, except that the child 

process is executed in the background with no access 
to the keyboard or the display. 

P_OVERLAY Overlays child process in memory location formerly 

occupied by parent. Same as an exec. . . call. 

path is the file name of the called child process. The spawn.. . function calls 
search for path using the standard operating system search algorithm: 

■ If no explicit extension is given, the functions search for the file as given. 
If the file is not found, they add .EXE and search again. If not found, they 
add .COM and search again. If still not found, they add .BAT and search 
once more. The command processor COMSPEC is used to run the 
executable file. 

■ If an extension is given, they search only for the exact file name. 

■ If only a period is given, they search only for the file name with no 
extension. 

■ If path does not contain an explicit directory, spawn.. . functions that have 
the p suffix search the current directory, then the directories set with the 
operating system PATH environment variable. 

The suffixes p, I, and v, and e added to the spawn.. . "family name" specify 
that the named function operates with certain capabilities. 

p The function searches for the file in those directories specified by the 
PATH environment variable. Without the p suffix, the function 
searches only the current working directory. 

I The argument pointers argO, argl, . . ., argn are passed as separate 
arguments. Typically, the / suffix is used when you know in advance 
the number of arguments to be passed. 
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v The argument pointers argv[0], ..., arg[n] are passed as an array of 
pointers. Typically, the v suffix is used when a variable number of 
arguments is to be passed. 

e The argument envp can be passed to the child process, letting you 
alter the environment for the child process. Without the e suffix, 
child processes inherit the environment of the parent process. 

Each function in the spawn.. . family must have one of the two argument- 
specifying suffixes (either / or v). The path search and environment 
inheritance suffixes (p and e) are optional. 

For example, 

■ spawnl takes separate arguments, searches only the current directory for 
the child, and passes on the parent's environment to the child. 

■ spawnvpe takes an array of argument pointers, incorporates PATH in its 
search for the child process, and accepts the envp argument for altering 
the child's environment. 

The spawn.. . functions must pass at least one argument to the child process 
(argO or argv[0]). This argument is, by convention, a copy of path. (Using a 
different value for this th argument won't produce an error.) If you want to 
pass an empty argument list to the child process, then argO or argv[0] must 
be NULL. 

Under DOS 3.x, path is available for the child process; under earlier 
versions, the child process cannot use the passed value of the th argument 
(argO or argv[0]). 

When the / suffix is used, argO usually points to path, and argl, ...., argn 
point to character strings that form the new list of arguments. A mandatory 
null following argn marks the end of the list. 

When the e suffix is used, you pass a list of new environment settings 
through the argument envp. This environment argument is an array of 
character pointers. Each element points to a null-terminated character 
string of the form 

envvar = value 

where envvar is the name of an environment variable, and value is the string 
value to which envvar is set. The last element in envp[] is null. When envp is 
null, the child inherits the parents' environment settings. 

The combined length of argO + argl + ... + argn (or of argv[0] + argv[l] + ... 
+ argv[n]), including space characters that separate the arguments, must be 
< 260 bytes. Null-terminators are not counted. 
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Return value 



See also 



When a spawn. . . function call is made, any open files remain open in the 
child process. 

On a successful execution, the spawn.. . functions where mode is P_WAIT 
return the child process' exit status (0 for a normal termination). If the child 
specifically calls exit with a nonzero argument, its exit status can be set to a 
nonzero value. If mode is P_NOWAIT or PJSJOWAITO, the spawn 
functions return the process ID of the child process. This ID can be passed 
to cwait. 

On error, the spawn.. . functions return -1, and the global variable errno is 
set to one of the following: 

E2BIG Arg list too long 

EINVAL Invalid argument 

ENOENT Path or file name not found 

ENOEXEC Exec format error 

ENOMEM Not enough memory 

abort, atexit, cwait, _exit, exit, exec. . ., Jpreset, searchpath, system, wait 



_splitpath 



stdlib.h 



Function 
Syntax 



Remarks 



Splits a full path name into its components. 

void _splitpath (const char *path, char *drive, char *dir, char *name, char *ext); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 






■ 



_splitpath takes a file's full path name (path) as a string in the form 

X:\DIR\SUBDIR\NAME.EXT 

and splits path into its four components. It then stores those components in 
the strings pointed to by drive, dir, name, and ext . (All five components must 
be passed, but any of them can be a null, which means the corresponding 
component will be parsed but not stored.) The maximum sizes for these 
strings are given by the constants _MAX_DRIVE _MAX_DIR _MAX_PATH 
_MAX_FNAME and _MAX_EXT) (defined in stdlib.h), and each size 
includes space for the null-terminator. These constants are defined in 
stdlib.h. 



I 
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_splitpath 



Constant 



String 



Return value 
See also 



MAX_PATH 


path 


MAX_DRIVE 


drive; includes colon (:) 


MAX_DIR 


dir, includes leading and trailing backslashes (\) 


MAX_FNAME 


name 


MAX_EXT 


ext, includes leading dot (.) 



jsplitpath assumes that there is enough space to store each non-null 
component. 

When _splitpath splits path, it treats the punctuation as follows: 

■ drive includes the colon (C:, A:, and so on). 

■ dir includes the leading and trailing backslashes 
( \ BC\ include \, \ source \, and so on). 

■ name includes the file name. 

■ ext includes the dot preceding the extension (.C, .EXE, and so on). 

jnakepath and jsplitpath are invertible; if you split a given path with 
_splitpath, then merge the resultant components with jnakepath, you end up 
with path. 



None. 

Jullpath, jnakepath 



sprintf 



stdio.h 



Function 
Syntax 



Remarks 



See printf for details 
on format specifiers. 



Return value 



Writes formatted output to a string. 

int sprintf (char *buffer, const char *format[, argument, 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


" 


■ 


■ 


■ 



sprintf accepts a series of arguments, applies to each a format specifier 
contained in the format string pointed to by format, and outputs the 
formatted data to a string. 

sprintf applies the first format specifier to the first argument, the second to 
the second, and so on. There must be the same number of format specifiers 
as arguments. 

sprintf returns the number of bytes output, sprintf does not include the 
terminating null byte in the count. In the event of error, sprintf returns EOF. 
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sprintf 



See also 



fprintf, printf 



sqrt, sqrtl 



math.h 



Function 
Syntax 



Remarks 



Return value 



See also 



sqrt 
sqrtl 



Calculates the positive square root. 

double sqrt (double x) ; 

long double sqrtl (long double x) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 




■ 


■ 




■ 


■ 






■ 



sqrt calculates the positive square root of the argument x. 

sqrtl is the long double version; it takes a long double argument and returns 
a long double result. Error handling for these functions can be modified 
through the functions jnaiherr and jnatherrl. 

This function can be used with bed and complex types. 

On success, sqrt and sqrtl return the value calculated, the square root of x. If 
x is real and positive, the result is positive. If x is real and negative, the 
global variable errno is set to 

EDOM Domain error 

bed, complex, exp, log, pow 



srand 



stdlib.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Initializes random number generator. 

void srand (unsigned seed); 



I 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


' 


■ 


■ 



The random number generator is reinitialized by calling srand with an 
argument value of 1. It can be set to a new starting point by calling srand 
with a given seed number. 

None. 

rand, random, randomize 
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sscanf 



sscanf 

Function 
Syntax 



Remarks 



See scanf for details on 
format specifiers. 



stdio.h 



Return value 



Scans and formats input from a string. 

int sscanf (const char *buffer, const char *format[, address, 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 



See also 



sscanf scans a series of input fields, one character at a time, reading from a 
string. Then each field is formatted according to a format specifier passed 
to sscanf in the format string pointed to by format. Finally, sscanf stores the 
formatted input at an address passed to it as an argument following format. 
There must be the same number of format specifiers and addresses as there 
are input fields. 

sscanf might stop scanning a particular field before it reaches the normal 
end-of-field (whitespace) character, or it might terminate entirely, for a 
number of reasons. See scanf for a discussion of possible causes. 

sscanf returns the number of input fields successfully scanned, converted, 
and stored; the return value does not include scanned fields that were not 
stored. If no fields were stored, the return value is 0. 

If sscanf attempts to read at end-of-string, the return value is EOF. 

fscanf, scanf 



stackavail 



malloc.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Gets the amount of available stack memory. 

size_t stackavail (void) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 






■ 



stackavail returns the number of bytes available on the stack. This is the 
amount of dynamic memory that alloca can access. 

stackavail returns a size J value indicating the number of bytes available. 

alloca 
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stat 



See f stat. 



stat 



_status87 

Function 
Syntax 



Remarks 



Return value 



float.h 



Gets floating-point status. 

unsigned int _status87 (void) ; 
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■ 




■ 


■ 






■ 



_status87 gets the floating-point status word, which is a combination of the 
80x87 status word and other conditions detected by the 80x87 exception 
handler. 

The bits in the return value give the floating-point status. See float.h for a 
complete definition of the bits returned by _status87. 



stime 



time.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Sets system date and time. 

int stime (time_t *tp) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 








■ 



stime sets the system time and date, tp points to the value of the time as 
measured in seconds from 00:00:00 GMT, January 1, 1970. 

stime returns a value of 0. 

asctime, jtime, gettime, gmtime, localtime, time, tzset 




stpcpy 



string.h 



Function 



Copies one string into another. 
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stpcpy 



Syntax 



Remarks 

Return value 
See also 



char *stpcpy(char *dest, const char *src); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 






■ 



stpcpy copies the string src to dest, stopping after the terminating null 
character of src has been reached. 

stpcpy returns dest + strlen(src). 

strcpy 



strcat, Jstrcat 



string.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Appends one string to another. 

char *strcat(char *dest, const char *src); 

char far * far _fstrcat(char far *dest, const char far *src) 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 



strcat appends a copy of src to the end of dest . The length of the resulting 
string is strlen{dest) + strlen(src). 

strcat returns a pointer to the concatenated strings. 
Jstr* 



strchr, Jstrchr 



string.h 



Function 
Syntax 



Scans a string for the first occurrence of a given character. 

char *strchr(const char *s ; int c); /* C only */ 

char far * far _f strchr (const char far *s, int c) /* C and C++ */ 

const char *strchr(const char *s, int c); // C++ only 

char *strchr( char *s, int c); // C++ only 
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strchr, Jstrchr 



Remarks 



Return value 
See also 



DOS 


UNIX 


Win 16 


Win 32 
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ANSI C++ 


OS/2 


■ 


■ 


' 


■ 


■ 


■ 


■ 



strchr scans a string in the forward direction, looking for a specific 
character, strchr finds the first occurrence of the character c in the string s. 
The null-terminator is considered to be part of the string, so that, for 
example, 

strchr (strs,0) 

returns a pointer to the terminating null character of the string strs. 

strchr returns a pointer to the first occurrence of the character c in s; if c does 
not occur in s, strchr returns null. 

_fstr*, strcspn, strrchr 



strcmp, Jstrcmp 



string.h 



Function 
Syntax 



Remarks 



Return value 



See also 



Compares one string to another. 

int strcmp(const char *sl, const char *s2); 

int far _f strcmp (const char far *sl, const char far *s2); 



DOS 
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Win 16 


Win 32 
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ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


- 


■ 


■ 



strcmp performs an unsigned comparison of si to s2, starting with the first 
character in each string and continuing with subsequent characters until 
the corresponding characters differ or until the end of the strings is 
reached. 

strcmp returns a value that is 

■ < if si is less than s2 

■ == if si is the same as s2 

■ > if si is greater than s2 

_fstr*, strcmpi, strcoll, stricmp, strncmp, strncmpi, strnicmp 



■ 



strcmpi 



string.h 



Function 



Compares one string to another, without case sensitivity. 
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strcmpi 



Syntax 



Remarks 



int strcmpi (const char *sl, const char *s2); 



Return value 
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■ 


■ 




■ 






■ 



See also 



strcmpi performs an unsigned comparison of si to s2, without case 
sensitivity (same as stricmp — implemented as a macro). 

It returns a value (< 0, 0, or > 0) based on the result of comparing si (or part 
of it) to s2 (or part of it). 

The routine strcmpi is the same as stricmp. strcmpi is implemented through a 
macro in string.h and translates calls from strcmpi to stricmp. Therefore, to 
use strcmpi, you must include the header file string.h for the macro to be 
available. This macro is provided for compatibility with other C compilers. 

strcmpi returns an int value that is 

■ < if si is less than s2 

■ == if si is the same as s2 

■ > if si is greater than s2 

strcmp, strcoll, stricmp, strncmp, strncmpi, strnicmp 



strcoll 



string.h 



Function 
Syntax 



Remarks 
Return value 



Compares two strings. 

int strcoll (char *sl, char *s2); 



DOS 
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Win 16 
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ANSI C 
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■ 




■ 


■ 


■ 


■ 


■ 



See also 



strcoll compares the string pointed to by si to the string pointed to by s2, 
according to the current locale's LC_COLLATE category. 

strcoll returns a value that is 

■ < if si is less than s2 

■ == if si is the same as s2 
m > if si is greater than s2 

strcmp, strcmpi, stricmp, strncmp, strncmpi, strnicmp, strxfrm 
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strcpy, Jstrcpy 



string.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Copies one string into another. 

char *strcpy(char *dest, const char *src) ; 

char far * far _fstrcpy (char far *dest, const char far *src); 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 



Copies string src to dest, stopping after the terminating null character has 
been moved. 

strcpy returns dest . 

Jstr*, stpcpy 



strcspn, Jstrcspn 



string.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Scans a string for the initial segment not containing any subset of a given 
set of characters. 

size_t strcspn(const char *sl, const char *s2); 

size_t far *far _f strcspn (const char far *sl, const char far *s2) 



DOS 
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■ 


■ 


■ 


■ 


■ 


■ 


■ 



The strcspn functions search s2 until any one of the characters contained in 
si is found. The number of characters which were read in s2 is the return 
value. The string termination character is not counted. Neither string is 
altered during the search. 

strcspn returns the length of the initial segment of string si that consists 
entirely of characters not from string s2. 

_fstr*, strchr, strrchr 




strdate 



time.h 



Function 
Syntax 



Converts current date to string. 

char *_strdate(char *buf); 
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strdate 



Remarks 



Return value 
See also 



DOS 
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Win 16 


Win 32 
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ANSI C++ 


OS/2 


■ 




■ 


■ 






■ 



_strdate converts the current date to a string, storing the string in the buffer 
buf. The buffer must be at least 9 characters long. 

The string has the form MM/DD/YY where MM, DD, and YY are all two-digit 
numbers representing the month, day, and year. The string is terminated by 
a null character. 

_strdate returns buf, the address of the date string. 

asctime, dime, localtime, strftime, _strtime, time 



strdup, Jstrdup 



string.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Copies a string into a newly created location. 

char * strdup (const char *s); 

char far * far _f strdup (const char far *s) 
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ANSI C++ 
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■ 


■ 


" 


■ 






■ 



strdup makes a duplicate of string s, obtaining space with a call to malloc. 
The allocated space is (strlen(s) + 1) bytes long. The user is responsible for 
freeing the space allocated by strdup when it is no longer needed. 

strdup returns a pointer to the storage location containing the duplicated 
string, or returns null if space could not be allocated. 

free ,Jstr* 



strerror 



string.h 



Function 
Syntax 



Remarks 



Builds a customized error message. 

char *_strerror (const char *s); 
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■ 


■ 






■ 



_strerror lets you generate customized error messages; it returns a pointer 
to a null-terminated string containing an error message. 
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strerror 



Return value 



See also 



■ If s is null, the return value points to the most recent error message. 

■ If s is not null, the return value contains s (your customized error 
message), a colon, a space, the most-recently generated system error 
message, and a new line, s should be 94 characters or less. 

_strerror returns a pointer to a constructed error string. The error message 
string is constructed in a static buffer that is overwritten with each call to 
_strerror. 

perror, strerror 



strerror 



string.h 



Function 
Syntax 



Remarks 
Return value 

See also 



Returns a pointer to an error message string. 

char *strerror(int errnum) ; 
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■ 


■ 


■ 


■ 


■ 



strerror takes an int parameter errnum, an error number, and returns a 
pointer to an error message string associated with errnum. 

strerror returns a pointer to a constructed error string. The error message 
string is constructed in a static buffer that is overwritten with each call to 
strerror. 

perror, _strerror 



strftime 



time.h 



I 



Function 
Syntax 



Remarks 



Formats time for output. 

size_t strftime (char *s, size_t maxsize, const char *fmt, const struct tm *t) 
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■ 


■ 


■ 


■ 



strftime formats the time in the argument t into the array pointed to by the 
argument s according to the fmt specifications. The format string consists of 
zero or more directives and ordinary characters. Like printf, a directive 
consists of the % character followed by a character that determines the 
substitution that is to take place. All ordinary characters are copied 
unchanged. No more than maxsize characters are placed in s. 
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strftime 



The time is formatted according to the current locale's LC_TIME category. 
The following table describes the ANSI-defined format specifiers. 



Format specifier 


Substitutes 


%% 


Character % 


%a 


Abbreviated weekday name 


%A 


Full weekday name 


%b 


Abbreviated month name 


%B 


Full month name 


%c 


Date and time 


%d 


Two-digit day of the month (01 to 31) 


%H 


Two-digit hour (00 to 23) 


%l 


Two-digit hour (01 to 12) 


%j 


Three-digit day of the year (001 to 366) 


%m 


Two-digit month as a decimal number (1-12) 


%M 


Two-digit minute (00 to 59) 


%p 


AM or PM 


%S 


Two-digit second (00 to 59) 


%U 


Two-digit week number where Sunday is the first day of the week (00 




to 53) 


%w 


Weekday where is Sunday (0 to 6) 


%W 


Two-digit week number where Monday is the first day of the week (00 




to 53) 


%x 


Date 


%X 


Time 


%y 


Two-digit year without century (00 to 99) 


%Y 


Year with century 


' %Z 


Time zone name, or no characters if no time zone 



In addition to the ANSI C-defined format descriptors, the following 
POSIX-defined descriptors are also supported. Each format specifier begins 
with the percent character (%). 

Format specifier Substitutes 

You must define 

_ JJSELOCALES %C Century as a decimal number (00-99). For example, 1 992 => 1 9 

in order to use these %D Date in the format mm/dd/yy 

descriptors. %e Day of the month as a decimal number in a two-digit field with leading 

space (1-31) 

%h A synonym for %b 

%n Newline character 

%r 12-hour time (01-12) format with am/pm string i.e. "%I:%M:%S %p" 

%t Tab character 

%T 24-hour time (00-23) in the format "HH:MM:SS" 

%u Weekday as a decimal number (1 Monday - 7 Sunday) 
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You must define 

__USELOCALES__ 

in order to use these 

descriptors. 



In addition to these descriptors, strftime also supports the descriptor modi- 
fiers as defined by POSIX on the following descriptors: 

Descriptor modifier Substitutes 

%0d Day of the month using alternate numeric symbols 

%Oe Day of the month using alternate numeric symbols 

%OH Hour (24 hour) using alternate numeric symbols 

%OI Hour (1 2 hour) using alternate numeric symbols 

%Om Month using alternate numeric symbols 

%OM Minutes using alternate numeric symbols 

%OS Seconds using alternate numeric symbols 

%Ou Weekday as a number using alternate numeric symbols 

%OU Week number of the year using alternate numeric symbols 

%Ow Weekday as number using alternate numeric symbols 

%OW Week number of the year using alternate numeric symbols 

%Oy Year (offset from %C) using alternate numeric symbols 



Return value 
See also 



%0 modifier - when this modifier is used before any of the above sup- 
ported numeric format descriptors, for example %Od, the numeric value is 
converted to the corresponding ordinal string, if it exists. If an ordinal 
string does not exist then the basic format descriptor is used unmodified. 

For example, on 8/20/88 a %d format descriptor would produce 20 but 
%Od on the same day would produce 20 th . 

strftime returns the number of characters placed into s. If the number of 
characters required is greater than maxsize, strftime returns 0. 

localtime, mktime, time 



stricmp, Jstricmp 



string.h 



i 



Function 
Syntax 



Remarks 



Compares one string to another, without case sensitivity. 

int stricmp (const char *sl, const char *s2); 

int far ,_f stricmp (const char far *sl, const char far *s2) 
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UNIX 
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■ 


■ 



stricmp performs an unsigned comparison of si to s2, starting with the first 
character in each string and continuing with subsequent characters until 
the corresponding characters differ or until the end of the strings is 
reached. The comparison is not case sensitive. 
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stricmp, Jstricmp 



Return value 



See also 



It returns a value (< 0, 0, or > 0) based on the result of comparing si (or part 
of it) to s2 (or part of it). 

The routines stricmp and strcmpi are the same; strcmpi is implemented 
through a macro in string.h that translates calls from strcmpi to stricmp. 
Therefore, in order to use strcmpi, you must include the header file string.h 
for the macro to be available. 

stricmp returns an int value that is 

■ < if si is less than s2 

■ == if si is the same as s2 
m > if si is greater than s2 

Jstr*, strcmp, strcmpi, strcoll, strncmp, strncmpi, strnicmp 



strlen, Jstrlen 



string.h 



Function 
Syntax 



Calculates the length of a string. 

size_t strlen(const char *s); 

size t far f strlen (const char far *s) 



Remarks 
Return value 

See also 
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strlen calculates the length of s. 

strlen returns the number of characters in s, not counting the null- 
terminating character. 

Jstr* 



strlwr, fstrlwr 



■j _' 



string.h 



Function 
Syntax 



Remarks 



Converts uppercase letters in a string to lowercase. 

char *strlwr(char *s); 

char far * far _f strlwr (char char far *s) 
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strlwr converts uppercase letters in string s to lowercase according to the 
current locale's LC_CTYPE category. For the C locale, the conversion is 
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strlwr, fstrlwr 



Return value 
See also 



from uppercase letters (A to Z) to lowercase letters (a to z). No other charac- 
ters are changed. 

strlwr returns a pointer to the string s. 

Jstr*, strupr 



strncat, Jstrncat 



string.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Appends a portion of one string to another. 

char * strncat (char *dest, const char *src, size_t maxlen); 

char far * far _f strncat (char far *dest, const char far *src, size_t maxlen) 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 


■ 


■ 


■ 


■ 


■ 


■ 



strncat copies at most maxlen characters of src to the end of dest and then 
appends a null character. The maximum length of the resulting string is 
strlen(dest) + maxlen. 

strncat returns dest. 

Jstr* 



strncmp, Jstrncmp 



string.h 



Function 
Syntax 



Remarks 



Return value 



Compares a portion of one string to a portion of another. 

int strncmpfconst char *sl, const char *s2, size_t maxlen); 

int far _f strncmp (const char far *sl, const char far *s2, size_t maxlen) 
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I 



strncmp makes the same unsigned comparison as strcmp, but looks at no 
more than maxlen characters. It starts with the first character in each string 
and continues with subsequent characters until the corresponding charac- 
ters differ or until it has examined maxlen characters. 

strncmp returns an int value based on the result of comparing si (or part of 
it) to s2 (or part of it): 

■ < if si is less than s2 
m == if si is the same as s2 
u > if si is greater than s2 
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strncmp, Jstmcmp 



See also 



Jstr*, strcmp, strcoll, stricmp, strncmpi, strnicmp 



strncmpi 



string.h 



Function 
Syntax 

Remarks 



Return value 



Compares a portion of one string to a portion of another, without case 
sensitivity. 

int strncmpi (const char *sl, const char *s2, size_t n); 
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strncmpi performs a signed comparison of si to s2, for a maximum length of 
n bytes, starting with the first character in each string and continuing with 
subsequent characters until the corresponding characters differ or until n 
characters have been examined. The comparison is not case sensitive. 
(strncmpi is the same as strnicmp — implemented as a macro). It returns a 
value (< 0, 0, or > 0) based on the result of comparing si (or part of it) to s2 
(or part of it). 

The routines strnicmp and strncmpi are the same; strncmpi is implemented 
through a macro in string.h that translates calls from strncmpi to strnicmp. 
Therefore, in order to use strncmpi, you must include the header file 
string.h for the macro to be available. This macro is provided for compati- 
bility with other C compilers. 

strncmpi returns an int value that is 

■ < if si is less than s2 

■ == if si is the same as s2 

■ > if si is greater than s2 



strncpy, Jstrncpy 



string.h 



Function 
Syntax 



Copies a given number of bytes from one string into another, truncating or 
padding as necessary. 

char *strncpy(char *dest, const char *src, size_t maxlen); 

char far * far _f strncpy (char far *dest, const char far *src, size_t maxlen) 
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strncpy, Jstrncpy 



Remarks 

Return value 
See also 



strncpy copies up to maxlen characters from src into dest, truncating or null- 
padding dest. The target string, dest, might not be null-terminated if the 
length of src is maxlen or more. 

strncpy returns dest. 

Jstr* 



strnicmp, Jstmicmp 



string.h 



Function 
Syntax 



Remarks 



Return value 



See also 



Compares a portion of one string to a portion of another, without case 
sensitivity. 

int strnicmp (const char *sl, const char *s2, size_t maxlen); 

int far _f strnicmp (const char far *sl, const char far *s2, size_t maxlen) 
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strnicmp performs a signed comparison of si to s2, for a maximum length of 
maxlen bytes, starting with the first character in each string and continuing 
with subsequent characters until the corresponding characters differ or 
until the end of the strings is reached. The comparison is not case sensitive. 

It returns a value (< 0, 0, or > 0) based on the result of comparing si (or part 
of it) to s2 (or part of it). 

strnicmp returns an int value that is 

■ < if si is less than s2 

b == if si is the same as s2 

■ > if si is greater than s2 

Jstr* 
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strnset, Jstrnset 



string.h 



Function 
Syntax 



Sets a specified number of characters in a string to a given character. 

char *strnset(char *s, int ch, size_t n) ; 

char far * far _f strnset (char far *s, int ch, size_t n) 
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strnset, Jstrnset 



Remarks 

Return value 
See also 



strnset copies the character ch into the first n bytes of the string s. If 

n > strlen(s), then strlen(s) replaces n. It stops when n characters have been 

set, or when a null character is found. 

strnset returns s. 

Jstr* 



strpbrk, Jstrpbrk 



string.h 



Function 
Syntax 



Remarks 
Return value 
See also 



Scans a string for the first occurrence of any character from a given set. 



char *strpbrk (const char *sl, const char *s2); 

char far *far _f strpbrk (const char far *sl, const char far *s2) 

const char * strpbrk (const char *sl, const char *s2); 
char *strpbrk(char *sl, const char *s2); 



/* C only */ 

/* C and C++ */ 

// C++ only 
// C++ only 



strpbrk scans a string, si, for the first occurrence of any character appearing 
in s2. 

strpbrk returns a pointer to the first occurrence of any of the characters in s2. 
If none of the s2 characters occur in si, strpbrk returns null. 
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Jstr* 



strrchr, Jstrrchr 



string.h 



Function 
Syntax 



Scans a string for the last occurrence of a given character. 

char *strrchr (const char *s, int c); /* C only */ 

char far * far _f strrchr (const char far *s, int c) /* C and C++ */ 

const char * strrchr (const char *s, int c); // C++ only 

char *strrchf (char *s, int c); // C++ only 
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strrchr, Jstrrchr 



Remarks 

Return value 
See also 



strrchr scans a string in the reverse direction, looking for a specific 
character, strrchr finds the last occurrence of the character c in the string s. 
The null-terminator is considered to be part of the string. 

strrchr returns a pointer to the last occurrence of the character c. If c does 
not occur in s, strrchr returns null. 

Jstr*, strcspn, strchr 



strrev, fstrrev 



» _ 



string.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Reverses a string. 



char *strrev(char *s); 

char far * far fstrrevlchar far *s) 
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strrev changes all characters in a string to reverse order, except the 
terminating null character. (For example, it would change string\0 to 
gnirts\0.) 

strrev returns a pointer to the reversed string. 

Jstr* 



strset, Jstrset 



string.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Sets all characters in a string to a given character. 

char *strset(char *s, int ch) ; 

char far * far _f strset (char far *s, int ch) 
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strset sets all characters in the string s to the character ch. It quits when the 
terminating null character is found. 

strset returns s. 

Jstr*, setmem 
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strspn, Jstrspn 



strspn, Jstrspn 



string.h 



Function 
Syntax 



Remarks 
Return value 
See also 



Scans a string for the first segment that is a subset of a given set of 
characters. 

slze_t strspnfconst char *sl, const char *s2); 

size_t far _f strspn (const char far *sl, const char far *s2); 
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strspn finds the initial segment of string si that consists entirely of 
characters from string s2. 

strspn returns the length of the initial segment of si that consists entirely of 
characters from s2. 

Jstr* 



strstr, fstrstr 
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string.h 



Function 
Syntax 



Remarks 
Return value 

See also 



Scans a string for the occurrence of a given substring. 

char *strstr(const char *sl, const char *s2); 

char far * far _fstrstr(const char far *sl, const char far *s2) 

const char *strstr(const char *sl, const char *s2); 
char *strstr(char *sl, const char *s2); 
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/* C only */ 

/* C and C++ */ 

// C++ only 
// C++ only 



strstr scans si for the first occurrence of the substring s2. 

strstr returns a pointer to the element in si, where s2 begins (points to s2 in 
si). If s2 does not occur in si, strstr returns null. 

Jstr* 



strtime 



time.h 



Function 
Syntax 



Converts current time to string. 

char *_strtime(char *buf); 
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strtime 



Remarks 



Return value 
See also 
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_strtime converts the current time to a string, storing the string in the buffer 
buf. The buffer must be at least 9 characters long. 

The string has the following form: 

HH:MM:SS 

where HH, MM, and SS are all two-digit numbers representing the hour, 
minute, and second, respectively. The string is terminated by a null 
character. 

_strtime returns buf, the address of the time string. 

asctime, ctime, localtime, strftime, _strdate, time 



strtod, strtold 
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stdlib.h 



Function 
Syntax 



Remarks 



strtod 
strtold 



Convert a string to a double or long double value. 

double strtod (const char *s, char **endptr); 

long double _strtold(const char *s, char **endptr); 
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strtod converts a character string, s, to a double value, s is a sequence of 
characters that can be interpreted as a double value; the characters must 
match this generic format: 

[ws] [sn] [ddd] [.] [ddd] [fmt[sn]ddd] 

where 

[ws] = optional whitespace 
[sn] = optional sign (+ or -) 
[ddd] = optional digits 
[fmt] = optional e or E 
[.] = optional decimal point 

strtod also recognizes +INF and -INF for plus and minus infinity, and 
+NAN and -NAN for Not-a-Number. 



I 



Chapter 3, Run-time functions 



267 



strtod, _strtold 



Return value 



See also 



For example, here are some character strings that strtod can convert to 
double: 

+ 1231.1981 e-1 
502.85E2 
+ 2010.952 

strtod stops reading the string at the first character that cannot be 
interpreted as an appropriate part of a double value. 

If endptr is not null, strtod sets *endptr to point to the character that stopped 
the scan (*endptr = &cstopper). endptr is useful for error detection. 

_strtold is the long double version; it converts a string to a long double 

value. 

These functions return the value of s as a double (strtod) or a long double 
(_strtold). In case of overflow, they return plus or minus HUGE_VAL 
(strtod) or _LHUGE_VAL (_strtold). 

atof 



strtok, Jstrtok 



string.h 



Function 
Syntax 



Searches one string for tokens, which are separated by delimiters defined in 
a second string. 

char *strtok(char *sl, const char *s2); 

char far * far _f strtok (char far *sl, const char far *s2) 



Remarks 



Return value 
See also 
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strtok considers the string si to consist of a sequence of zero or more text 
tokens, separated by spans of one or more characters from the separator 
string s2. 

The first call to strtok returns a pointer to the first character of the first token 
in si and writes a null character into si immediately following the returned 
token. Subsequent calls with null for the first argument will work through 
the string si in this way, until no tokens remain. 

The separator string, s2, can be different from call to call. 

strtok returns a pointer to the token found in si. A NULL pointer is 
returned when there are no more tokens. 

Jstf* 
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strtol 



strtol 



stdlib.h 



Function 
Syntax 



Remarks 



Converts a string to a long value. 

long strtol(const char *s, char **endptr, int radix); 
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strtol converts a character string, s, to a long integer value, s is a sequence of 
characters that can be interpreted as a long value; the characters must 
match this generic format: 

[ws] [sn] [0] [x] [ddd] 

where 

[ws] = optional whitespace 
[sn] = optional sign (+ or -) 
[0] = optional zero (0) 
[x] = optional x or X 
[ddd] = optional digits 

strtol stops reading the string at the first character it doesn't recognize. 

If radix is between 2 and 36, the long integer is expressed in base radix. If 
radix is 0, the first few characters of s determine the base of the value being 
converted. 



First 
character 



Second 
character 



String interpreted as 







1-9 



1-7 
xorX 



Octal 

Hexadecimal 

Decimal 



If radix is 1, it is considered to be an invalid value. If radix is less than or 
greater than 36, it is considered to be an invalid value. 

Any invalid value for radix causes the result to be and sets the next 
character pointer *endptr to the starting string pointer. 

If the value in s is meant to be interpreted as octal, any character other than 
to 7 will be unrecognized. 

If the value in s is meant to be interpreted as decimal, any character other 
than to 9 will be unrecognized. 
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strtol 



Return value 
See also 



If the value in s is meant to be interpreted as a number in any other base, 
then only the numerals and letters used to represent numbers in that base 
will be recognized. (For example, if radix equals 5, only to 4 will be 
recognized; if radix equals 20, only to 9 and A to J will be recognized.) 

If endptr is not null, strtol sets *endptr to point to the character that stopped 
the scan (*endptr = &cstopper). 

strtol returns the value of the converted string, or on error. 

atoi, atol, strtoul 



strtold 



See strtod. 



strtoul 



stdlib.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Converts a string to an unsigned long in the given radix. 

unsigned long strtoul (const char *s, char **endptr, int radix); 
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strtoul operates the same as strtol, except that it converts a string str to an 
unsigned long value (where strtol converts to a long). Refer to the entry for 
strtol for more information. 

strtoul returns the converted value, an unsigned long, or on error. 

atol, strtol 



strupr, Jstrupr 



string.h 



Function 
Syntax 



Converts lowercase letters in a string to uppercase. 

char *strupr(char *s); 

char far * far _f strupr (char far *s) 
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strupr, Jstrupr 



Remarks 



Return value 
See also 



strupr converts lowercase letters in string s to uppercase according to the 
current locale's LC_CTYPE category. For the default C locale, the 
conversion is from lowercase letters (a to z) to uppercase letters (A to Z). No 
other characters are changed. 

strupr returns s. 

Jstr*, strlwr 



strxfrm 



string.h 



Function 
Syntax 



Remarks 



Transforms a portion of a string to a specified collation. 

size_t strxfrm (char *target, const char *source, size_t n) ; 
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strxfrm transforms the string pointed to by source into the string target for 
no more than n characters. The transformation is such that if the strcmp 
function is applied to the resulting strings, its return corresponds with the 
return values of the strcoll function. 

No more than n characters, including the terminating null character, are 
copied to target. 

strxfrm transforms a character string into a special string according to the 
current locale's LC_COLLATE category. The special string that is built can 
be compared with another of the same type, byte for byte, to achieve a 
locale-correct collation result. These special strings, which can be thought 
of as keys or tokenized strings, are not compatible across the different 
locales. 

The tokens in the tokenized strings are built from the collation weights 
used by strcoll from the active locale's collation tables. 

Processing stops only after all levels have been processed for the character 
string or the length of the tokenized string is equal to the maxlen 
parameter. 

All redundant tokens are removed from each level's set of tokens. 

The tokenized string buffer must be large enough to contain the resulting 
tokenized string. The length of this buffer depends on the size of the 
character string, the number of collation levels, the rules for each level and 
whether there are any special characters in the character string. Certain 
special characters can cause extra character processing of the string 
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strxfrm 



Return value 



See also 



resulting in more space requirements. For example, the French character 
"ce" will take double the space for itself because in some locales, it expands 
to two collation weights at each level. Substrings that have substitutions 
will also cause extra space requirements. 

There is no safe formula to determine the required string buffer size, but at 
least (levels * string length) are required. 

Number of characters copied not including the terminating null character. 
If the value returned is greater than or equal to n, the content of target is 
indeterminate. 

strcmp, strcoll, strncpy 



swab 



stdlib.h 



Function 
Syntax 



Remarks 



Return value 



Swaps bytes. 

void swab(char *from, char *to, int nbytes); 
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swab copies nbytes bytes from the from string to the to string. Adjacent even- 
and odd-byte positions are swapped. This is useful for moving data from 
one machine to another machine with a different byte order, nbytes should 
be even. 

None. 



system 



stdlib.h 



Function 
Syntax 



Remarks 



Issue an operating system command. 

int system (const char * command ) ; 
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system invokes the operating system command processor to execute an op- 
erating system command, batch file, or other program named by the string 
command, from inside an executing C program. 

To be located and executed, the program must be in the current directory or 
in one of the directories listed in the PATH string in the environment. 
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system 



Return value 



See also 



The COMSPEC environment variable is used to find the command 
processor program file, so that file need not be in the current directory. 

If command is a NULL pointer, system returns nonzero if a command proces- 
sor is available. 

If command is not a NULL pointer, system returns if the command 
processor was successfully started. 

If an error occurred, a -1 is returned and errno is set to one of the following: 

ENOENT Path or file function not found 

ENOEXEC Exec format error 

, ENOMEM Not enough memory 

exec. . ., Jpreset, searchpath, spawn ... 



tan, tanl 



math.h 



Function 
Syntax 



Remarks 



Return value 
See also 



fan 
fan/ 



Calculates the tangent. 

double tanfdouble x); 

long double tanl (long double x) 
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tan calculates the tangent. Angles are specified in radians. 

tanl is the long double version; it takes a long double argument and returns 
a long double result. Error handling for these routines can be modified 
through the functions jnatherr and jnatherrl. 

This function can be used with bed and complex types. 

tan and tanl return the tangent of x, sin(x)/cos(x). 

acos, asin, atan, atanl, bed, complex, cos, sin 



I 



tanh, tanhl 



math.h 



Function 



Calculates the hyperbolic tangent. 
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tanh, tanhl 



Syntax 



Remarks 



Return value 
See also 



tanh 
tanhl 



double tanh (double x) ; 

long double tanhl (long double x); 
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tanh computes the hyperbolic tangent, sinh(x)/cosh(x). 

tanhl is the long double version; it takes a long double argument and 
returns a long double result. Error handling for these functions can be 
modified through the functions jnatherr and jnatherrl. 

This function can be used with bed and complex types. 

tanh and tanhl return the hyperbolic tangent of x. 

bed, complex, cos, cosh, sin, sinh, tan 



tell 



io.h 



Function 
Syntax 



Remarks 
Return value 

See also 



Gets the current position of a file pointer. 

long tell(int handle); 
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tell gets the current position of the file pointer associated with handle and 
expresses it as the number of bytes from the beginning of the file. 

tell returns the current file pointer position. A return of -1 (long) indicates 
an error, and the global variable errno is set to 

EBADF Bad file number 

fgetpos, f seek, f tell, Iseek 



tempnam 



stdio.h 



Function 
Syntax 



Creates a unique file name in specified directory. 

char * tempnam (char *dir, char *prefix) . 
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tempnam 



Remarks 



Return value 



See also 
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The tempnam function creates a unique file name in arbitrary directories. 
The unique file is not actually created; tempnam only verifies that it does not 
currently exist. It attempts to use the following directories, in the order 
shown, when creating the file name: 

■ The directory specified by the TMP environment variable. 

■ The dir argument to tempnam. 

■ The PJmpdir definition in stdio.h. If you edit stdio.h and change this 
definition, tempnam will not use the new definition. 

■ The current working directory. 

If any of these directories is NULL, or undefined, or does not exist, it is 
skipped. 

The prefix argument specifies the first part of the file name; it cannot be 
longer than 5 characters, and cannot contain a period (.). A unique file 
name is created by concatenating the directory name, the prefix, and 6 
unique characters. Space for the resulting file name is allocated with malloc; 
when this file name is no longer needed, the caller should call free to free it. 

If you do create a temporary file using the name constructed by tempnam, it 
is your responsibility to delete the file name (for example, with a call to 
remove). It is not deleted automatically, (tmpfile does delete the file name.) 

If tempnam is successful, it returns a pointer to the unique temporary file 
name, which the caller can pass to free when it is no longer needed. 
Otherwise, if tempnam cannot create a unique file name, it returns NULL. 

mktemp, tmpfile, tmpnam 



textattr 



conio.h 




Function 
Syntax 



Sets text attributes. 

void textattr (int newattr); 



Remarks 
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textattr lets you set both the foreground and background colors in a single 
call. (Normally, you set the attributes with textcolor and textbackground.) 
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textattr 



This function does not affect any characters currently onscreen; it affects 
only those characters displayed by functions (such as cprintf) performing 
text mode, direct video output after this function is called. 

The color information is encoded in the newattr parameter as follows: 



7 


6 


5 


4 


3 


2 


1 





B 


b 


b 


b 


f 


f 


f 


f 



















In this 8-bit newattr parameter, 

Mffff is the 4-bit foreground color (0 to 15). 

■ bbb is the 3-bit background color (0 to 7). 

■ B is the blink-enable bit. 

If the blink-enable bit is on, the character blinks. This can be accomplished 
by adding the constant BLINK to the attribute. 

If you use the symbolic color constants defined in conio.h for creating text 
attributes with textattr, note the following limitations on the color you 
select for the background: 

■ You can select only one of the first eight colors for the background. 

■ You must shift the selected background color left by 4 bits to move it into 
the correct bit positions. 

These symbolic constants are listed in the following table: 



Symbolic 
constant 



Numeric 
value 



Foreground or 
background? 



BLACK 





Both 


BLUE 


1 


Both 


GREEN 


2 


Both 


CYAN 


3 


Both 


RED 


4 


Both 


MAGENTA 


5 


Both 


BROWN 


6 


Both 


LIGHTGRAY 


7 


Both 


DARKGRAY 


8 


Foreground only 


LIGHTBLUE 


9 


Foreground only 


LIGHTGREEN 


10 


Foreground only 


LIGHTCYAN 


11 


Foreground only 
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Return value 
See also 



Symbolic 
constant 



LIGHTRED 
LIGHTMAGENTA 
YELLOW 
WHITE ■ 
BLINK 



Numeric 


Foreground or 


value 


background? 


12 


Foreground only 


13 


Foreground only 


14 


Foreground only 


15 


Foreground only 


128 


Foreground only 



This function should not be used in Win32s or Win32 GUI applications. 

None. 

gettextinfo, highvideo, lowvideo, normvideo, textbackground, textcolor 



textbackground 



conio.h 



Function 
Syntax 



Remarks 



Selects new text background color. 

void textbackground ( int newcolor); 
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textbackground selects the background color. This function works for 
functions that produce output in text mode directly to the screen, newcolor 
selects the new background color. You can set newcolor to an integer from 
to 7, or to one of the symbolic constants defined in conio.h. If you use 
symbolic constants, you must include conio.h. 

Once you have called textbackground, all subsequent functions using direct 
video output (such as cprintf) will use newcolor. textbackground does not 
affect any characters currently onscreen. 

The following table lists the symbolic constants and the numeric values of 
the allowable colors: 



Symbolic constant 


Numeric value 


BLACK 





BLUE 


1 


GREEN 


2 


CYAN 


3 


RED 


4 


MAGENTA 


5 


BROWN 


6 


UGHTGRAY 


7 



ES 
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textbackground 



Return value 
See also 



This function should not be used in Win32s or Win32 GUI applications. 

None. 

gettextinfo, textattr, textcolor 



textcolor 



conio.h 



Function 
Syntax 



Remarks 



Selects new character color in text mode. 

void textcolorfint newcolor) ; 
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textcolor selects the foreground character color. This function works for the 
console output functions, newcolor selects the new foreground color. You 
can set newcolor to an integer as given in the table below, or to one of the 
symbolic constants defined in conio.h. If you use symbolic constants, you 
must include conio.h. 

Once you have called textcolor, all subsequent functions using direct video 
output (such as cprintf) will use newcolor. textcolor does not affect any 
characters currently onscreen. 

The following table lists the allowable colors (as symbolic constants) and 
their numeric values: 



Symbolic constant 


Numeric value 


BLACK 





BLUE 


1 


GREEN 


2 


CYAN 


3 


RED 


4 


MAGENTA 


5 


BROWN 


6 


LIGHTGRAY 


7 - 


DARKGRAY 


8 


LIGHTBLUE 


9 


LIGHTGREEN 


10 


LIGHTCYAN 


11 


LIGHTRED 


12 


LIGHTMAGENTA 


13 
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Symbolic constant 



Numeric value 



Return value 
See also 



YELLOW 

WHITE 

BLINK 



14 

15 

128 



You can make the characters blink by adding 128 to the foreground color. 
The predefined constant BLINK exists for this purpose; for example, 

textcolor (CYAN + BLINK); 

Some monitors do not recognize the intensity signal used to create the eight 
"light" colors (8-15). On such monitors, the light colors are displayed as 
their "dark" equivalents (0-7). Also, systems that do not display in color 
can treat these numbers as shades of one color, special patterns, or special 
attributes (such as underlined, bold, italics, and so on). Exactly what you'll 
see on such systems depends on your hardware. 

This function should not be used in Win32s or Win32 GUI applications. 

None. 

gettextinfo, highvideo, lowvideo, normvideo, textattr, textbackground 



textmode 



conio.h 



Function 
Syntax 



Remarks 



Puts screen in text mode. 

void textmode (int newmode) ; 
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textmode selects a specific text mode. 

You can give the text mode (the argument newmode) by using a symbolic 
constant from the enumeration type textjnodes (defined in conio.h). 

The most commonly used textjnodes type constants and the modes they 
specify are given in the following table. Some additional values are defined 
in conio.h. 



B 



Symbolic 
constant 



Text mode 



LASTMODE 


Previous text mode 


BW40 


Black and white, 40 columns 


C40 . 


Color, 40 columns 
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textmode 



Return value 
See also 



Symbolic 
constant 



Text mode 



BW80 
C80 
MONO 
C4350 



Black and white, 80 columns 
Color, 80 columns 
Monochrome, 80 columns 
EGA 43-line and VGA 50-line modes 



When textmode is called, the current window is reset to the entire screen, 
and the current text attributes are reset to normal, corresponding to a call to 

normvideo. 

Specifying LASTMODE to textmode causes the most recently selected text 
■mode to be reselected. 

textmode should be used only when the screen or window is in text mode 
(presumably to change to a different text mode). This is the only context in 
which textmode should be used. When the screen is in graphics mode, use 
restorecrtmode instead to escape temporarily to text mode. 

This function should not be used in Win32s or Win32 GUI applications. 

None. 

gettextinfo, window 



time 



time.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Gets time of day. 

time_t time(time_t * timer) 
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time gives the current time, in seconds, elapsed since 00:00:00 GMT, January 
1, 1970, and stores that value in the location pointed to by timer, provided 
that timer is not a NULL pointer. 

time returns the elapsed time in seconds, as described. 

asctime, ctime, diff time, f time, gettime, gmtime, localtime, settime, stime, tzset 



tmpfile 



stdio.h 



Function 



Opens a "scratch" file in binary mode. 
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Syntax 

Remarks 

Return value 
See also 



FILE *tmpfile(void); 
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tmpfile creates a temporary binary file and opens it for update (w + b). The 
file is automatically removed when it's closed or when your program 
terminates. 

tmpfile returns a pointer to the stream of the temporary file created. If the 
file can't be created, tmpfile returns NULL. 

fopen, tmpnam 



tmpnam 



stdio.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Creates a unique file name. 

char *tmpnam(char *s); 
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tmpnam creates a unique file name, which can safely be used as the name of 
a temporary file, tmpnam generates a different string each time you call it, 
up to TMP_MAX times. TMP_MAX is defined in stdio.h as 65,535. 

The parameter to tmpnam, s, is either null or a pointer to an array of at least 
LJmpnam characters. LJmpnam is defined in stdio.h. If s is NULL, tmpnam 
leaves the generated temporary file name in an internal static object and 
returns a pointer to that object. If s is not NULL, tmpnam places its result in 
the pointed-to array, which must be at least LJmpnam characters long, and 
returns s. 

If you do create such a temporary file with tmpnam, it is your responsibility 
to delete the file name (for example, with a call to remove). It is not deleted 
automatically, (tmpfile does delete the file name:) 

If s is null, tmpnam returns a pointer to an internal static object. Otherwise, 
tmpnam returns s. 

tmpfile 
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toascii 



toascii 

Function 
Syntax 



Remarks 
Return value 



ctype.h 



Translates characters to ASCII format. 

int toascii (int c) ; 
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toascii is a macro that converts the integer c to ASCII by clearing all but the 
lower 7 bits; this gives a value in the range to 127. 

toascii returns the converted value of c. 



tolower 



ctype.h 



Function 
Syntax 



Remarks 



Return value 



Translates characters to lowercase. 

int _tolower(int ch) ; 
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Jtolower is a macro that does the same conversion as tolower, except that it 
should be used only when ch is known to be uppercase (A-Z). 

To use Jolower, you must include ctype.h. 

Jolower returns the converted value of ch if it is uppercase; otherwise, the 
result is undefined. 



tolower 



ctype.h 



Function 
Syntax 



Remarks 



Translates characters to lowercase. 

int tolower (int ch) ; 
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tolower is a function that converts an integer ch (in the range EOF to 255) to 
its lowercase value. The function is affected by the current locale's 
LC_CTYPE category. For the default C locale, ch is converted to a lowercase 
letter (a to z, if it was uppercase, A to Z). All others are left unchanged. 
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Return value tolower returns the converted value of ch if it is uppercase; it returns all 

others unchanged. 



Joupper 



ctype.h 



Function 
Syntax 



Remarks 



Return value 



Translates characters to uppercase. 

int _toupper(int ch) ; 
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_toupper is a macro that does the same conversion as toupper, except that it 
should be used only when ch is known to be lowercase letter (a to z). 

To use Joupper, you must include ctype.h. 

Joupper returns the converted value of ch if it is lowercase; otherwise, the 
result is undefined. 



toupper 



ctype.h 



Function 
Syntax 



Remarks 



Return value 



Translates characters to uppercase. 

int toupper (int ch) ; 
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toupper is a function that converts an integer ch (in the range EOF to 255) to 
its uppercase value. The function is affected by the current locale's 
LC_CTYPE category. For the default C locale, ch is converted to an upper- 
case letter (A to Z; if it was lowercase, a to z). All others are left unchanged. 

toupper returns the converted value of ch if it is lowercase; it returns all 
others unchanged. 



B 



tzset 



time.h 



Function 
Syntax 



Sets value of global variables _daylight, Jimezone, and Jznatne. 

void tzset (void) 



Chapter 3, Run-time functions 



283 



tzset 
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Remarks 



Return value 
See also 



tzset is available on XENIX systems. 

tzset sets the _daylight, Jimezone, and _tzname global variables based on the 
environment variable TZ. The library functions ftime and localtime use these 
global variables to adjust Greenwich Mean Time (GMT) to the local time 
zone. The format of the TZ environment string is: 

TZ = zzz[+/-]d[d][lll] 

where zzz is a three-character string representing the name of the current 
time zone. All three characters are required. For example, the string "PST" 
could be used to represent pacific standard time. 

[+/-]rf[rf] is a required field containing an optionally signed number with 1 
or more digits. This number is the local time zone's difference from GMT in 
hours. Positive numbers adjust westward from GMT. Negative numbers 
adjust eastward from GMT. For example, the number 5 = EST, +8 = PST, 
and -1 = continental Europe. This number is used in the calculation of the 
global variable Jimezone. Jimezone is the difference in seconds between 
GMT and the local time zone. 

/// is an optional three-character field that represents the local time zone 
daylight saving time. For example, the string "PDT" could be used to 
represent pacific daylight saving time. If this field is present, it causes the 
global variable _daylight to be set nonzero. If this field is absent, _daylight is 
set to zero. 

If the TZ environment string isn't present or isn't in the preceding form, a 
default TZ = "EST5EDT" is presumed for the purposes of assigning values 
to the global variables jiaylight, Jimezone, and Jzname. 

The global variable Jzname[0] points to a three-character string with the 
value of the time-zone name from the TZ environment string. Jzname[l] 
points to a three-character string with the value of the daylight saving 
time-zone name from the TZ environment string. If no daylight saving 
name is present, Jzname[l] points to a null string. 

None. 

asctime, ctime, ftime, gmtime, localtime, stime, time 
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ultoa 

Function 
Syntax 



Remarks 



stdlib.h 



Return value 
See also 



Converts an unsigned long to a string. 

char *ultoa (unsigned long value, char *string, int radix); 
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ultoa converts value to a null-terminated string and stores the result in 
string, value is an unsigned long. 

radix specifies the base to be used in converting value; it must be between 2 
and 36, inclusive, ultoa performs no overflow checking, and if value is 
negative and radix equals 10, it does not set the minus sign. 

The space allocated for string must be large enough to hold the returned 
string, including the terminating null character (\0). ultoa can return up to 
33 bytes. 

ultoa returns string. 

itoa, Itoa 



umask 



io.h 



Function 
Syntax 



Remarks 



Sets file read /write permission mask. 

unsigned umask (unsigned mode) ; 
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The umask function sets the access permission mask used by open and creat. 
Bits that are set in mode will be cleared in the access permission of files 
subsequently created by open and creat. 

The mode can have one of the following values, defined in sys\stat.h: 



B 



Value of mode 



Access permission 



SJWRITE 

SJREAD 

S IREADIS IWRITE 



Permission to write 
Permission to read 
Permission to read and write 
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umask 



Return value 
See also 



The previous value of the mask. There is no error return. 
creat, open 



ungetc 



stdio.h 



Function 
Syntax 



Remarks 



Return value 
See also 



Pushes a character back into input stream. 

int ungetc (int c, FILE *stream) ; 
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ungetc pushes the character c back onto the named input stream, which 
must be open for reading. This character will be returned on the next call to 
getc or fread for that stream. One character can be pushed back in all 
situations. A second call to ungetc without a call to getc will force the 
previous character to be forgotten. A call to fflush, fseek, fsetpos, or rewind 
erases all memory of any pushed-back characters. 

On success, ungetc returns the character pushed back; it returns EOF if the 
operation fails. 

f getc, getc, getchar 



ungetch 



conio.h 



Function 
Syntax 



Remarks 



Return value 



See also 



Pushes a character back to the keyboard buffer. 



int ungetch (int ch) ; 
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ungetch pushes the character ch back to the console, causing ch to be the 
next character read. The ungetch function fails if it is called more than once 
before the next read. 

ungetch returns the character ch if it is successful. A return value of EOF 
indicates an error. 

This function should not be used in Win32s or Win32 GUI applications. 

getch, getche 
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unixtodos 

Function 
Syntax 



Remarks 



Return value 
See also 



dos.h 



Converts date and time from UNIX to DOS format. 

void unixtodos (long time, struct date *d, struct time *t); 
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unixtodos converts the UNIX-format time given in time to DOS format and 
fills in the date and time structures pointed to by d and t. 

time must not represent a calendar time earlier than Jan. 1, 1980 00:00:00. 

None. 

dostounix 



unlink 



io.h 



Function 
Syntax 



Remarks 



Return value 



See also 



Deletes a file. 

int unlink(const char *filename); 
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unlink deletes a file specified by filename. Any drive, path, and file name can 
be used as a filename. Wildcards are not allowed. 

Read-only files cannot be deleted by this call. To remove read-only files, 
first use chmod or _rtl_chmod to change the read-only attribute. 

If your file is open, be sure to close it before unlinking it. 

On successful completion, unlink returns 0. On error, it returns -1 and the 
global variable errno is set to one of the following values: 



i 



EACCES 
ENOENT 

chmod, remove 



Permission denied 

Path or file name not found 
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unlock 



unlock 

Function 
Syntax 



Remarks 



Return value 
See also 



io.h 



Releases file-sharing locks. 

int unlock(int handle, long offset, long length); 
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unlock provides an interface to the operating system file-sharing 
mechanism, unlock removes a lock previously placed with a call to lock. To 
avoid error, all locks must be removed before a file is closed. A program 
must release all locks before completing. 

unlock returns on success, -1 on error. 

lock, locking, sopen 



utime 



utime.h 



Function 
Syntax 



Remarks 



Return value 



Sets file time and date. 

int utime(char *path, struct utimbuf *times); 
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utime sets the modification time for the file path. The modification time is 
contained in the utimbuf structure pointed to by times. This structure is 
defined in utime.h, and has the following format: 

struct utimbuf { 

time_t actime; /* access time */ 

time_t modtime; /* modification time */ ■ 

}; 

The FAT file system supports only a modification time; therefore, on FAT 
file systems utime ignores actime and uses only modtime to set the file's 
modification time. 

If times is NULL, the file's modification time is set to the current time. 

utime returns if it is successful. Otherwise, it returns -1, and the global 
variable errno is set to one of the following: 
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utime 



See also 



EACCES Permission denied 
EMFILE Too many open files 
ENOENT Path or file name not found 

setftime, stat, time 



va_arg, va_end, va_start 



stdarg.h 



Function 
Syntax 



Remarks 



Implement a variable argument list. 

void va_start(va_list ap, lastfix); 
type va_arg(va_list ap, type); 
void va_end(va_list ap) ; 
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Some C functions, such as vfprintf and vprintf, take variable argument lists 
in addition to taking a number of fixed (known) parameters. The va_arg, 
va_end, and va_start macros provide a portable way to access these 
argument lists. They are used for stepping through a list of arguments 
when the called function does not know the number and types of the 
arguments being passed. 

The header file stdarg.h declares one type (va_list) and three macros 
(va_start, va_arg, and va_end). 

■ va_Hst This array holds information needed by vajirg and va_end. When 
a called function takes a variable argument list, it declares a variable ap of 
type vajist 

■ va_start: This routine (implemented as a macro) sets ap to point to the 
first of the variable arguments being passed to the function. va_start must 
be used before the first call to vajirg or va_end. 

■ va_start takes two parameters: ap and lastfix. (ap is explained under vajist 
in the preceding paragraph; lastfix is the name of the last fixed parameter 
being passed to the called function.) 

■ va_arg: This routine (also implemented as a macro) expands to an 
expression that has the same type and value as the next argument being 
passed (one of the variable arguments). The variable ap to va_arg should 
be the same ap that va_start initialized. 

Because of default promotions, you can't use char, unsigned char, or 
float types with va_arg. 



EB 
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va_arg, va_end, va_start 



Return value 
See also 



The first time va_arg is used, it returns the first argument in the list. Each 
successive time va_arg is used, it returns the next argument in the list. It 
does this by first dereferencing ap, and then incrementing ap to point to 
the following item. va_arg uses the type to both perform the dereference 
and to locate the following item. Each successive time vajirg is invoked, 
it modifies ap to point to the next argument in the list. 

■ va_end: This macro helps the called function perform a normal return. 
va_end might modify ap in such a way that it cannot be used unless 
va_start is recalled. va_end should be called after va_arg has read all the 
arguments; failure to do so might cause strange, undefined behavior in 
your program. 

va_start and va_end return no values; vajarg returns the current argument in 
the list (the one that ap is pointing to). 

v...printf,v...scanf 



vfprintf 



stdio.h 



Function 
Syntax 



Remarks 



See printf for details 
on format specifiers. 



Return value 



Writes formatted output to a stream. 

int vfprintf (FILE *stream, const char *format, va_list arglist) 
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See also 



The v. . .printf functions are known as alternate entry points for the . . .printf 
functions. They behave exactly like their ...printf counterparts, but they 
accept a pointer to a list of arguments instead of an argument list. 

vfprintf accepts a pointer to a series of arguments, applies to each argument 
a format specifier contained in the format string pointed to by format, and 
outputs the formatted data to a stream. There must be the same number of 
format specifiers as arguments. 

vfprintf returns the number of bytes output. In the event of error, vfprintf 
returns EOF. 

printf, va_arg,va_end,va_start 



vfscanf 



stdio.h 



Function 



Scans and formats input from a stream. 
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vfscanf 



Syntax 



Remarks 



See scant for details 
on format specifiers. 



int vfscanf (FILE *stream, const char *format, va_list arglist), 



Return value 
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See also 



The v... sccrnf functions are known as alternate entry points for the ...scanf 
functions. They behave exactly like their ...scanf counterparts, but they 
accept a pointer to a list of arguments instead of an argument list. 

vfscanf scans a series of input fields, one character at a time, reading from a 
stream. Then each field is formatted according to a format specifier passed 
to vfscanf in the format string pointed to by format. Finally, vfscanf stores the 
formatted input at an address passed to it as an argument following format. 
There must be the same number of format specifiers and addresses as there 
are input fields. 

vfscanf might stop scanning a particular field before it reaches the normal 
end-of-field (whitespace) character, or it might terminate entirely, for a 
number of reasons. See scanf for a discussion of possible causes. 

vfscanf returns the number of input fields successfully scanned, converted, 
and stored; the return value does not include scanned fields that were not 
stored. If no fields were stored, the return value is 0. 

If vfscanf attempts to read at end-of-file, the return value is EOF. 

fscanf, scanf, va_arg, va_end, va_start 



vprintf 



stdarg.h 



Function 
Syntax 



Remarks 



See printf for details 
on format specifiers. 



Writes formatted output to stdout. 

int vprintf (const char *format, va_list arglist), 
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The v. . .printf functions are known as alternate entry points for the . . .printf 
functions. They behave exactly like their ...printf counterparts, but they 
accept a pointer to a list of arguments instead of an argument list. 

vprintf accepts a pointer to a series of arguments, applies to each a format 
specifier contained in the format string pointed to by format, and outputs 
the formatted data to stdout. There must be the same number of format 
specifiers as arguments. 



i 
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vprintf 



Return value 
See also 



When you use the SS!=DS flag in 16-bit applications, vprintf assumes that 

the address being passed is in the SS segment. 

For Win32s or Win32 GUI applications, stdout must be redirected. 

vprint returns the number of bytes output. In the event of error, vprint 
returns EOF. 

freopen, printf, va_arg, va_end, va_start 



vscanf 



stdarg.h 



Function 
Syntax 



Remarks 



See scan/for details 
on format specifiers. 



Return value 



Scans and formats input from stdin. 

int vscanf (const char *format, va_list arglist); 
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See also 



The v. . .scanf functions are known as alternate entry points for the . . .scanf 
functions. They behave exactly like their ... scanf counterparts, but they 
accept a pointer to a list of arguments instead of an argument list. 

vscanf scans a series of input fields, one character at a time, reading from 
stdin. Then each field is formatted according to a format specifier passed to 
vscanf in the format string pointed to by format. Finally, vscanf stores the 
formatted input at an address passed to it as an argument following format. 
There must be the same number of format specifiers and addresses as there 
are input fields. 

vscanf might stop scanning a particular field before it reaches the normal 
end-of-field (whitespace) character, or it might terminate entirely, for a 
number of reasons. See scanf for a discussion of possible causes. 

For Win32s or Win32 GUI applications, stdin must be redirected. 

vscanf returns the number of input fields successfully scanned, converted, 
and stored; the return value does not include scanned fields that were not 
stored. If no fields were stored, the return value is 0. 

If vscanf attempts to read at end-of-file, the return value is EOF. 

freopen, f scanf, scanf, va_arg, va_end, va_start 
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vsprintf 



vsprintf 

Function 
Syntax 



Remarks 



See printf for details 
on format specifiers. 



Return value 
See also 



stdarg.h 



Writes formatted output to a string. 

int vsprintf (char *buffer, const char *format, va_list arglist) ; 
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The v. . .printf functions are known as alternate entry points for the . . .printf 
functions. They behave exactly like their . . .printf counterparts, but they 
accept a pointer to a list of arguments instead of an argument list. 

vsprintf accepts a pointer to a series of arguments, applies to each a format 
specifier contained in the format string pointed to by format, and outputs 
the formatted data to a string. There must be the same number of format 
specifiers as arguments. 

vsprintf returns the number of bytes output. In the event of error, vsprintf 
returns EOF. 

printf, va_arg, va_end, va_start 



vsscanf 



stdarg.h 



Function 
Syntax 



Remarks 



See scant for details 
on format specifiers. 



Scans and formats input from a stream. 

int vsscanf (const char *buffer, const char *format, va_list arglist); 
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The v. . .scanf functions are known as alternate entry points for the . . .scanf 
functions. They behave exactly like their . . .scanf counterparts, but they 
accept a pointer to a list of arguments instead of an argument list. 

vsscanf scans a series of input fields, one character at a time, reading from a 
stream. Then each field is formatted according to a format specifier passed 
to vsscanf 'in the format string pointed to by format. Finally, vsscanf stores the 
formatted input at an address passed to it as an argument following format. 
There must be the same number of format specifiers and addresses as there 
are input fields. 
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vsscanf 



Return value 



See also 



vsscanf might stop scanning a particular field before it reaches the normal 
end-of-field (whitespace) character, or it might terminate entirely, for a 
number of reasons. See scanf for a discussion of possible causes. 

vsscanf returns the number of input fields successfully scanned, converted, 
and stored; the return value does not include scanned fields that were not 
stored. If no fields were stored, the return value is 0. 

If vsscanf attempts to read at end-of-string, the return value is EOF. 

fscanf, scanf, sscanf, va_arg, va_end, va_start, vfscanf 



wait 



process.h 



Function 
Syntax 



Remarks 



Return value 



Waits for one or more child processes to terminate. 

int waitfint *statloc); 
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The wait function waits for one or more child processes to terminate. The 
child processes must be those created by the calling program; wait cannot 
wait for grandchildren (processes spawned by .child processes). If statloc is 
not NULL, it points to location where wait will store the termination status. 
If the child process terminated normally (by calling exit, or returning from 
main), the termination status word is defined as follows: 



Bits 0-7 



Zero. 



Bits 8-1 5 The least significant byte of the return code from the child 

process. This is the value that is passed to exit, or is returned 
from main. If the child process simply exited from main with- 
out returning a value, this value will be unpredictable. 

If the child process terminated abnormally, the termination status word is 
defined as follows: 

Bits 0-7 Termination information about the child: 



1 
2 
3 

Bits 8-15 Zero. 



Critical error abort. 

Execution fault, protection exception. 

External termination signal. 



When wait returns after a normal child process termination it returns the 
process ID of the child. 
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wait 



See also 



When wait returns after an abnormal child termination it returns -1 to the 
parent and sets errno to EINTR. 

If wait returns without a child process completion it returns a -1 value and 
sets errno to 



ECHILD 

cwait, spawn 



No child process exists 



wcstombs 



stdlib.h 



Function 
Syntax 



Remarks 



Return value 



Converts a wchar_t array into a multibyte string. 

size_t wcstombs (char *s, const wchar_t *pwcs, size_t n) ; 
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wcstombs converts the type wchar_t elements contained in pwcs into a 
multibyte character string s. The process terminates if either a null character 
or an invalid multibyte character is encountered. 

No more than n bytes are modified. If n number of bytes are processed 
before a null character is reached, the array s is not null terminated. 

The behavior of wcstombs is affected by the setting of LC_CTYPE category 
of the current locale. 

If an invalid multibyte character is encountered, wcstombs returns (size_t) 
-1. Otherwise, the function returns the number of bytes modified, not 
including the terminating code, if any. 



wctomb 



stdlib.h 



i 



Function 
Syntax 



Remarks 



Converts wchar_t code to a multibyte character. 

int wctomb(char *s, wchar_t wc); 
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If s is not null, wctomb determines the number of bytes needed to represent 
the multibyte character corresponding to wc (including any change in shift 
state). The multibyte character is stored in s. At most MB_CUR_MAX 
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wctomb 



characters are stored. If the value of wc is zero, wctomb is left in the initial 
state. 

The behavior of wctomb is affected by the setting of LC_CTYPE category of 
the current locale. 

Return value If s is a NULL pointer, wctomb returns a nonzero value if multibyte 

character encodings do have state-dependent encodings, and a zero value if 
they do not. 

If s is not a NULL pointer, wctomb returns -1 if the wc value does not 
represent a valid multibyte character. Otherwise, wctomb returns the 
number of bytes that are contained in the multibyte character correspond- 
ing to wc. In no case will the return value be greater than the value of 
MB CUR MAX macro. 



wherex 



conio.h 



Function 
Syntax 



Remarks 

Return value 
See also 



Gives horizontal cursor position within window. 

int wherex (void) ; 
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wherex returns the x-coordinate of the current cursor position (within the 
current text window). 

This function should not be used in Win32s or Win32 GUI applications. 

wherex returns an integer in the range 1 to the number of columns in the 
current video mode. 

gettextinfo,gotoxy, wherey 



wherey 



conio.h 



Function 
Syntax 



Gives vertical cursor position within window. 

int wherey (void) ; 
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wherey 



Remarks 

Return value 
See also 



wherey returns the y-coordinate of the current cursor position (within the 
current text window). 

This function should not be used in Win32s or Win32 GUI applications. 

wherey returns an integer in the range 1 to the number of rows in the 
current video mode. 

gettextinfo, gotoxy, wherex 



window 



conio.h 



Function 
Syntax 



Remarks 



Return value 
See also 

write 



Defines active text mode window. 

void window(int left, int top, int right, int bottom); 
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window defines a text window onscreen. If the coordinates are in any way 
invalid, the call to window is ignored. 

left and top are the screen coordinates of the upper left corner of the 
window, right and bottom are the screen coordinates of the lower right 
corner. 

The minimum size of the text window is one column by one line. The 
default window is full screen, with the coordinates: 

1,1/CR 

where C is the number of columns in the current video mode, and R is the 
number of rows. 

This function should not be used in Win32s or Win32 GUI applications. 

None. 

clreol, clrscr, delline, gettextinfo, gotoxy, insline, puttext, textmode 



B 



io.h 



Remarks 



Obsolete function. See rtl write. 
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write 



write 

Function 
Syntax 



Remarks 



io.h 



Return value 



Writes to a file. 

int write (int handle, void *buf, unsigned len); 
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write writes a buffer of data to the file or device named by the given handle, 
handle is a file handle obtained from a creat, open, dup, or dup2 call. 

This function attempts to write len bytes from the buffer pointed to by buf 
to the file associated with handle. Except when write is used to write to a text 
file, the number of bytes written to the file will be no more than the number 
requested. The maximum number of bytes that write can write is 
UINT_MAX -1, because UINTJVIAX is the same as -1, which is the error 
return indicator for write. On text files, when write sees a linefeed (LF) 
character, it outputs a CR/LF pair. UINT_MAX is defined in limits.h. 

If the number of bytes actually written is less than that requested, the 
condition should be considered an error and probably indicates a full disk. 
For disks or disk files, writing always proceeds from the current file 
pointer. For devices, bytes are sent directly to the device. For files opened 
with the 0_APPEND option, the file pointer is positioned to EOF by write 
before writing the data. 

write returns the number of bytes written. A write to a text file does not 
count generated carriage returns. In case of error, write returns -1 and sets 
the global variable errno to one of the following values: 



EACCES 
EBADF 



Permission denied 
Bad file number 



See also 



creat, Iseek, open, read, _rtl_write 
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Global variables 



Borland C++ provides you with predefined global variables for many 
common needs, such as dates, times, command-line arguments, and so on. 
This chapter defines and describes them. 



8087 



dos.h 



Function 
Syntax 



Remarks 



In a 16-bit Windows 

program, the value is 

1 if any coprocessor 

is detected. 



Coprocessor chip flag. 

extern int _8087; 
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The _8087 variable is set to a nonzero value (1, 2, or 3) if the startup code 
autodetection logic detects a floating-point coprocessor (an 8087, 80287, or 
80387, respectively). The _8087 variable is set to otherwise. 

The autodetection logic can be overridden by setting the 87 environment 
variable to YES or NO. (The commands are SET 87=YES and SET 87=NO; it is 
essential that there be no spaces before or after the equal sign.) If you use 
the 87 environment variable, the _8087 variable will reflect the override. 

Refer to Chapter 8 in the Programmer's Guide for more information about the 
87 environment variable. 



_argc 



dos.h 



Function 
Syntax 



Keeps a count of command-line arguments. 

extern int _argc; 
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_argc 



Remarks 



_argc has the value of argc passed to main when the program starts. 



argv 



dos.h 



Function 
Syntax 



Remarks 



An array of pointers to command-line arguments. 

extern char **_argv; 
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_argv points to an array containing the original command-line arguments 
(the elements of argv[]) passed to main when the program starts. 



_ctype 



ctype.h 



Function 
Syntax 



Remarks 



An array of character attribute information. 

extern char _ctype[]; 
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jotype is an array of character attribute information indexed by ASCII value 
+ 1. Each entry is a set of bits describing the character. 

This array is used only by routines affected by the C locale, such as isdigit, 
isprint, and so on. 



_daylight 



time.h 



Function 
Syntax 



Remarks 
See also 



Indicates whether daylight saving time adjustments will be made. 

extern int _daylight; 
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i 



_daylight is used by the time and date functions. It is set by the tzset, ftime, 
and localtime functions to 1 for daylight saving time, for standard time. 



timezone 
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directvideo 



_directvideo 

Function 
Syntax 



Remarks 



conio.h 



Flag that controls video output. 

extern int _directvideo; 
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_directvideo controls whether your program's console output (from cputs, for 
example) goes directly to the video RAM (_directvideo = 1) or goes via ROM 
BIOS calls (_directvideo = 0). 

The default value is _directvideo = 1 (console output goes directly to video 
RAM). To use _directvideo = 1, your system's video hardware must be 
identical to IBM display adapters. Setting jlirectvideo = allows your 
console output to work on any system that is IBM BIOS-compatible. 
_directvideo should be used only in character-based applications. It should 
not be used in 16-bit Windows, Win32s, or Win32 GUI applications. 



environ 



dos.h 



Function 
Syntax 



Remarks 



Accesses the operating system environment variables. 

extern char ** _environ; 
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_environ is an array of pointers to strings; it is used to access and alter the 
operating system environment variables. Each string is of the form 

envvar = varvalue 

where envvar is the name of an environment variable (such as PATH), and 
varvalue is the string value to which envvar is set (such as C : \BIN; C : \D0S). 
The string varvalue can be empty. 

When a program begins execution, the operating system environment set- 
tings are passed directly to the program. Note that env, the third argument 
to main, is equal to the initial setting of _environ. 

The _environ array can be accessed by getenv; however, the putenv function 
is the only routine that should be used to add, change or delete the _environ 
array entries. This is because modification can resize and relocate the 
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environ 



See also 



process environment array, but _environ is automatically adjusted so that it 
always points to the array. 

getenv, putenv 



errno, _doserrno, _sys_errlist, _sys_nerr 



dos.h, errno.h 



Function 
Syntax 



Remarks 



Enable perror to print error messages. 

extern int _doserrno; 
extern int errno; 
extern char **_sys_errlist; 
extern int _sys_nerr; 
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errno, _sys_errlist, and _sys_nerr are used by perror to print error messages 
when certain library routines fail to accomplish their appointed tasks. 
jioserrno is a variable that maps many operating-system error codes to 
errno; however, perror does not use jioserrno directly. See the header files 
winbase.h and winerror.h for the list of operating-system errors. 

■ errno: When an error in a math or system call occurs, errno is set to indi- 
cate the type of error. Sometimes errno and jioserrno are equivalent. At 
other times, errno does not contain the actual operating system error 
code, which is contained in jioserrno instead. Still other errors might 
occur that set only errno, not jioserrno. 

m jioserrno: When an operating-system call results in an error, jioserrno is 
set to the actual operating-system error code, errno is a parallel error 
variable inherited from UNIX. 

■ _sys_errlist: To provide more control over message formatting, the array 
of message strings is provided in _sysjerrlist. You can use errno as an 
index into the array to find the string corresponding to the error number. 
The string does not include any newline character. 

■ _sysjierr: This variable is defined as the number of error message strings 
in _sys_errlist. 

The following table gives mnemonics and their meanings for the values 
stored in _sys_errlist. The list is alphabetically ordered for easier reading. 
For the numerical ordering, see the header file errno.h. 
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errno, _dosermo, _sys_errlist, _sys_nerr 



Mnemonic 


16-bit description 


32-bit description 


E2BIG 


Arg list too long 


Arg list too long 


EACCES 


Permission denied 


Permission denied 


EBADF 


Bad file number 


Bad file number 


ECHILD 




No child process 


ECONTR 


Memory blocks destroyed 


Memory blocks destroyed 


ECURDIR 


Attempt to remove CurDir 


Attempt to remove CurDir 


EDEADLOCK 




Locking violation 


EDOM 


Domain error 


Math argument 


EEXIST 


File already exists 


File already exists 


EFAULT 


Unknown error 


Unknown error 


EINTR 




Interrupted function call 


EINVACC 


Invalid access code 


Invalid access code 


EINVAL 


Invalid argument 


Invalid argument 


EINVDAT 


Invalid data 


Invalid data 


EINVDRV 


Invalid drive specified 


Invalid drive specified 


EINVENV 


Invalid environment 


Invalid environment 


EINVFMT 


Invalid format 


Invalid format 


EINVFNC 


Invalid function number 


Invalid function number 


EINVMEM 


Invalid memory block address 


Invalid memory block 
address 


EIO 




Input/Output error 


EMFILE 


Too many open files , 


Too many open files 


ENAMETOOLONG 




File name too long 


ENFILE 




Too many open files 


ENMFILE 


No more files 


No more files 


ENODEV 


No such device 


No such device 


ENOENT 


No such file or directory 


No such file or directory 


ENOEXEC 


Exec format error 


Exec format error 


ENOFILE 


No such file or directory 


File not found 


ENOMEM 


Not enough memory 


Not enough core 


ENOPATH 


Path not found 


Path not found 


ENOSPC 




No space left on device 


ENOTSAM 


Not same device 


Not same device 


ENXIO 




No such device or address 


EPERM 




Operation not permitted 


EPIPE 




Broken pipe 


ERANGE 


Result out of range 


Result too large 


EROFS 




Read-only filesystem 


ESPIPE 




Illegal seek 


EXDEV 


Cross-device link 


Cross-device link 


EZERO 


Error 


Error 



The following list gives mnemonics for the actual DOS error codes to which 
_doserrno can be set. (This value of _doserrno may or may not be mapped 
(through errno) to an equivalent error message string in _sys_errlist. 
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errno, _doserrno, _sys_errlist, _sys_nerr 



Mnemonic 



DOS error code 



E2BIG 


Bad environ 


EACCES 


Access denied 


EACCES 


Bad access 


EACCES 


Is current dir 


EBADF 


Bad handle 


EFAULT 


Reserved 


EINVAL 


Bad data 


EINVAL 


Bad function 


EMFILE 


Too many open 


ENOENT 


No such file or directory 


ENOEXEC 


Bad format 


ENOMEM 


Out of memory 


ENOMEM 


Bad block 


EXDEV 


-Bad drive 


EXDEV 


Not same device 



Refer to your DOS reference manual for more information about DOS error 
return codes. 



floatconvert 



stdio.h 



Function 
Syntax 



Remarks 



Links the floating-point formats. 

extern int _floatconvert; 
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Floating-point output requires linking of conversion routines used by 
printf, scanf, and any variants of these functions. To reduce executable size, 
the floating-point formats are not automatically linked. However, this 
linkage is done automatically whenever your program uses a mathematical 
routine or the address is taken of some floating-point number. If neither of 
these actions occur the missing floating-point formats can result in a run- 
time error. 

The following program illustrates how to set up your program to properly 
execute. 
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floatconvert 



/* PREPARE TO OUTPUT FLOATING-POINT NUMBERS. */ 
Mnclude <stdio.h> 

#pragma extref _floatconvert 

void main() { 

printfCd = %lf\n\ 1); 
} 



fmode 



fcntl.h 



Function 
Syntax 



Remarks 



Determines default file-translation mode. 

extern int _fmode; 
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Jmode determines in which mode (text or binary) files will be opened and 
translated. The value of Jmode is 0_TEXT by default, which specifies that 
files will be read in text mode. If Jmode is set to 0_BINARY, the files are 
opened and read in binary mode. (0_TEXT and 0_BINARY are defined in 
fcntLh.) 

In text mode, carriage-return/linefeed (CR/LF) combinations are translated 
to a single linefeed character (LF) on input. On output, the reverse is true: 
LF characters are translated to CR/LF combinations. 

In binary mode, no such translation occurs. 

You can override the default mode as set by Jmode by specifying a t (for 
text mode) or b (for binary mode) in the argument type in the library 
functions fopen, fdopen, and freopen. Also, in the function open, the argument 
access can include either 0_BINARY or 0_TEXT, which will explicitly 
define the file being opened (given by the open pathname argument) to be in 
either binary or text mode. 



new handler 



Function 
Syntax 



Traps new allocation miscues. 

typedef void (*pvf)(); 
pvf _new_handler;. 
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new handler 



Remarks 



As an alternative, you can set using the function set_new_handler, like this: 

pvf set_new_handler (pvf p) ; 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 






■ 



jiewjiandler contains a pointer to a function that takes no arguments and 
returns void. If operator new() is unable to allocate the space required, it 
will call the function pointed to by jiewjiandler; if that function returns it 
will try the allocation again. By default, the function pointed to by 
jiewjiandler terminates the application. The application can replace this 
handler, however, with a function that can try to free up some space. This is 
done by assigning directly to jiewjiandler or by calling the function 
set jiewjiandler, which returns a pointer to the former handler. 

jiewjiandler is provided primarily for compatibility with C++ version 1.2. 
In most cases this functionality can be better provided by overloading 
operator new(). 



osmajor, _osminor, _osversion 



dos.h 



Function 
Syntax 



Remarks 



Contain the major and minor operating-system version numbers. 

extern unsigned char _osmajor; 
extern unsigned char _osminor; 
extern unsigned _osversion; 
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ANSI C++ 
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■ 


■ 






■ 



The major and minor version numbers are available individually through 
jjsmajor and jjsminor. jjsmajor is the major version number, and jjsminor 
is the minor version number. For example, if you are running DOS version 
3.2, jjsmajor will be 3 and jjsminor will be 20. 

jjsversion is functionally identical to jjersion. See the discussion of jersion. 

These variables can be useful when you want to write modules that will 
run on DOS versions 2.x and 3.x. Some library routines behave differently 
depending on the DOS version number; other routines work under DOS 3.x 
only. (For example, refer to jtljjpen, creatnew, and ioctl in this book.) 
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-PSP 



-PSP 

Function 

Syntax 
Remarks 



dos.h 

Contains the segment address of the program segment prefix (PSP) for the 
current program. 

extern unsigned int' _psp; 
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■ 


■ 






■ 



The PSP is a DOS process descriptor; it contains initial DOS information 
about the program. 

Refer to the DOS Programmer's Reference Manual for more information on 
the PSP. 



threadid 



stddef.h 



Function 
Syntax 



Remarks 



Pointer to thread ID. 

extern long _threadid; 
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■ 






■ 



Jhreadid is a long integer that contains the ID of the currently executing 
thread. It is implemented as a macro, and should be declared only by 
including stddef.h. 



_ JhrowExceptionName, _ JhrowFileName, _ JhrowLineNumber except.h 



Function 
Syntax 



Remarks 



Generates information about a thrown exception. 

extern char * throwExceptionName; 

extern char * throwFileName; 

extern char * throwLineNumber ; 
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■ 






■ 



Use these global variables to get the name and location of a thrown 
exception. The output for each of the variables is a printable character 
string. 
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timezone 



To get the file name and line number for a thrown exception with 

throwFileName and throwLineNumber, you must compile the module 

with the -xp compiler option. 



timezone 



time.h 



Function 
Syntax 



Remarks 



See also 



Contains difference in seconds between local time and GMT. 

extern long _timezone; 
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■ 


■ 






■ 



Jimezone is used by the time-and-date functions. 

This variable is calculated by then tzset function; it is assigned a long value 
that is the difference, in seconds, between the current local time and 
Greenwich mean time. 

_daylight 



tzname 



time.h 



Function 
Syntax 



Remarks 



Array of pointers to time-zone names. 

extern char * _tzname[2] 



DOS 


UNIX 
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The global variable Jzname is an array of pointers to strings containing 
abbreviations for time-zone names. _tzname[0] points to a three-character 
string with the value of the time-zone name from the TZ environment 
string. The global variable _tzname[l] points to a three-character string with 
the value of the daylight-saving time-zone name from the TZ environment 
string. If no daylight saving name is present, _tzname[l] points to a null 
string. 



version 



dos.h 



Function 
Syntax 



Contains the operating-system version number. 

extern unsigned _yersion; 
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version 



Remarks 



DOS 


UNIX 
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■ 


■ 






■ 



_version contains the operating-system version number, with the major 
version number in the high byte and the minor version number in the low 
byte. For a 32-bit application, this layout of the version number is in the 
low word. (For DOS version x.y, the x is the major version number, and y is 
the minor.) 



wscroll 



conio.h 



Function 
Syntax 



Remarks 



Enables or disables scrolling in console I/O functions. 

extern int wscroll 
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■ 


■ 






■ 



jwscroll is a console I/O flag. Its default value is 1. If you set jwscroll to 0, 
scrolling is disabled. This can be useful for drawing along the edges of a 
window without having your screen scroll. 

jwscroll should be used only in character-based applications. It is available 
for Easy Win but it should not be used in any GUI application. 
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The C++ iostream classes 



Online help provides 

sample programs for 

many iostream 

classes. 



The stream class library in C++ consists of several classes distributed in two 
separate hierarchical trees. See the Programmer's Guide, Chapter 6, for an 
illustration of the class hierarchies. This reference presents some of the 
most useful details of these classes, in alphabetical order. The following 
cross-reference table tells which classes belong to which header files. 



Header file 



Classes 



constrea.h 

iostream.h 

fstream.h 
strstrea.h 



conbuf, constream (These classes are available only for console-mode 

applications.) 

ios, iostream, iostream_withassign, istream, istream_withassign, 

ostream, ostream_withassign, streambuf 

filebuf, fstream, fstreambase, ifstream, ofstream 

istrstream, ostrstream, strstream, strstreambase, strstreambuf 



conbuf class 



constrea.h 



conbuf is available Specializes streambuf to handle console output. 

only for console- 
mode applications. 

Public constructor 



Constructor conbuf ( ) 

Makes an unattached conbuf. 

Public member functions 



clreol 



clrscr 



void clreol () 

Clears to end of line in text window. 

void clrscr () 
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conbuf class 



delline 

gotoxy 

highvideo 

insline 

lowvideo 

normvideo 

overflow 

setcursortype 

textattr 

textbackground 

textcolor 

textmode 

wherex 

wherey 



Clears the defined screen. 

void delline () 

Deletes a line in the window. 

void gotoxy (int x; int y) 

Positions the cursor in the window at the specified location. 

void highvideo () 

Selects high-intensity characters. 

void insline () 

Inserts a blank line. 

void lowvideo () 

Selects low-intensity characters. 

void normvideo () 

Selects normal-intensity characters. 

virtual int overflow ( int = EOF ) 

Flushes the conbuf to its destination. 

void setcursortype (int cur_type) 

Selects the cursor appearance. 

void textattr (int newattribute) 

Selects cursor appearance. 

void textbackground (int newcolor) 

Selects the text background color. 

void textcolor ( int newcolor) 

Selects character color in text mode. 

static void textmode (int newmode) 

Puts the screen in text mode. 

int wherex () 

Gets the horizontal cursor position. 

int wherey () 

Gets the vertical cursor position. 
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conbuf class 



window 



void window (int left, int top, int' right, int bottom) 
Defines the active window. 



constream class 



constrea.h 



constream is 

available only for 

console-mode 

applications. 



Constructor 



Provides console output streams. This class is derived from ostream. 

Public constructor 

constream () 

Provides an unattached output stream to the console. 



Public member functions 



clrscr 



rdbuf 



textmode 



window 



void clrscr () 

Clears the screen. 

conbuf *rdbuf() 

Returns a pointer to this constream's assigned conbuf. 

void textmode (int newmode) 

Puts the screen in text mode. 

void window (int left, int top, int right, int bottom) 

Defines the active window. 



filebuf class 



fstream.h 



Specializes streambuf to use files for input and output of characters. The 
filebuf class manages buffer allocation and deletion, and seeking within a 
file. This class also permits unbuffered file I/O by using the appropriate 
constructor or the member function filebuf v.setbuf. By default, files are 
opened in openprot mode to allow reading and writing. See page 319 for a 
list of file-opening modes. 

The filebuf class only provides basic services for file I/O. Input and output 
to a filebuf can only be done with the low-level functions provided by 
streambuf. Higher level classes provide formatting services. 
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filebuf class 



Public constructors 



Constructor 



Constructor 



filebuf ();' 

Makes a filebuf that isn't attached to a file. 

filebuf (int fd) ; 

Makes a filebuf attached to a file as specified by file descriptor fd. 

filebuf (int fd, char *buf, int n) ; 

Makes a filebuf attached to a file specified by the file descriptor fd, and uses 
buf as the storage area. The size of buf is sufficient to store n bytes. If buf is 
NULL or n is non-positive, the filebuf is unbuffered. 



Public data members 



openprot 



static const int openprot 

The default file protection. The exact value of openprot should not be of 
interest to the user. Its purpose is to set the file permissions to read and 
write. 



Public member functions 



attach 



close 



fd 



is_open 



filebuf* attach (int fd) 

Connects this closed filebuf to a file specified by the file descriptor fd. If the 
file buffer is already open, attach fails and returns NULL. Otherwise, the file 
buffer is connected to fd. 

filebuf* closed 

Flushes and closes the file. Generally, it is not necessary to make an explicit 
call to close at your program's end because proper file closing is ensured by 
the filebuf destructor. An explicit call to close is useful when you want to 
disconnect the filebuf from your program. 

Returns on error, for example, if the file was already closed. Otherwise, 
the function returns a reference to the filebuf (the this pointer). 

int fd() 

Returns the file descriptor or EOF. 

int is_open() ; 
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filebuf class 



open 



overflow 



seekoff 



setbuf 



sync 



underflow 



Returns nonzero if the hie is open. 

filebuf* open(const char *filename, int mode, 
int prot = filebuf : :openprot) ; 

Opens the file specified by filename and connects to it. The file-opening 
mode is specified by mode. 

virtual int overflow(int c = EOF); 

Flushes a buffer to its destination. Every derived class should define the 
actions to be taken. 

virtual streampos seekoff (streamoff offset, dir ios: :seek_dir, int mode); 

Moves the file get/put pointer an offset number of bytes. The pointer is 
moved in the direction specified by dir relative to the current position, mode 
can specify read (ios::in), write (ios::out), or both. If mode is ios::in, the get 
pointer is adjusted. If mode is ioswout, the put pointer is adjusted. 

If successful, the seekoff function returns a streampos-type value that 
indicates the new file pointer position. 

The function can fail if the file does not support repositioning or you 
request an illegal pointer repositioning, for example, beyond the end of the 
file. On failure, seekoff returns EOF. The file pointer position is undefined. 

virtual streambuf* setbuf (char *buf, int len); 

Allocates buf of size len for use by the filebuf. If buf is NULL or len is a non- 
positive value, the filebuf is unbuffered.' 

On success, setbuf returns a pointer to the filebuf. A failure occurs if the file 
is open and a buffer has been allocated. On failure, setbuf returns NULL 
and no changes are made to the buffering status. 

virtual int sync ( ) ; 

Establishes consistency between internal data structures and the external 
stream representation. 

virtual int underflow! ); 

Makes input available. This is called when no more data exists in the input 
buffer. Every derived class should define the actions to be taken. 



fstream class 



fstream.h 



This stream class, derived from fstreambase and iostream, provides for 
simultaneous input and output on a filebuf. 
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fstream class 



Public constructors 



Constructor 



Constructor 



Constructor 



Constructor 



f stream ( ); 

Makes an fstream that isn't attached to a file. 

fstream (const char *name, int mode, int prot 



filebuf : :openprot) ; 



Makes an fstream, opens a file with access as specified by mode, and 
connects to it. See page 319 for access options provided by ios::open_mode. 

fstream (int fd) ; 

Makes an fstream and connects to an open-file descriptor specified by fd. 

fstream(int fd, char *buf, int n) ; 

Makes a fstream attached to a file specified by the file descriptor fd, and uses 
buf as the storage area. The size of buf is sufficient to store n bytes. If buf is 
NULL or n is non-positive, the fstream is unbuffered. 

Public member functions 



open 



rdbuf 



void open(const char *name, int mode, int prot = filebuf : :openprot) ; 

Opens a file specified by name for an fstream. The file-opening mode is 
specified by the variable mode. 

filebuf* rdbuf (); 

Returns the filebuf used. 



fstreambase class 



fstream.h 



This stream class, derived from ios, provides operations common to file 
streams. It serves as a base for fstream, ifstream, and ofstream. 

Public constructors 



Constructor 



Constructor 



fstreambase () ; 

Makes an fstreambase that isn't attached to a file. 

fstreambase (const char *name, int mode, int = filebuf : :openprot) ; 
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fstreambase class 



Constructor 



Constructor 



attach 

close 

open 

rdbuf 

setbuf 



Makes an fstreambase, opens a file specified by name in mode specified by 
mode, and connects to it. 

fstreambase (int fd) ; 

Makes an fstreambase and connects to an open-file descriptor specified by fd. 

fstreambase (int fd, char *buf, int len); 

Makes an fstreambase connected to an open-file descriptor specified by fd. 
The buffer is specified by buf and the buffer size is len. 

Public member functions 

void attach (int fd) ; 

Connects to an open-file descriptor. 

void close () ; 

Closes the associated filebuf and file. 

void open(const char *name, int mode, int prot = filebuf : :openprot) ; 
Opens a file for an fstreambase. The file-opening mode is specified by mode. 
filebuf* rdbuf (); 
Returns the filebuf used. 

void setbuf (char *buf, int len); 

Reserves an area of memory pointed to by buf. The area is sufficiently large 
to store len number of bytes. 



ifstream class 



fstream.h 



Constructor 



Constructor 



This stream class, derived from fstreambase and [stream, provides input 
operations on a filebuf. 

Public constructors 

if stream () ; 

Makes an ifstream that isn't attached to a file. 

ifstream(const char *name, int mode = ios::in, 
int prot = filebuf : :openprot) ; 
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ifstream class 



Constructor 



Constructor 



Makes an ifstream, opens a file for input in protected mode, and connects to 
it. By default, the file is not created if it does not already exist. 

ifstream (int fd) ; 

Makes an ifstream and connects to an open-file descriptor fd. 

i f stream ( int fd, char *buf, int buf_len) ; 

Makes an ifstream connected to an open file. The file is specified by its 
descriptor, fd. The ifstream uses the buffer specified by bufoi length bufjen. 

Public member functions 



open 
rdbuf 



void open (const char *name, int mode, int prot = filebuf : :openprot) ; 
Opens a file for an ifstream. 
filebuf* rdbuf (); 
Returns the filebuf used. 



ios class 



iostream.h 



Provides operations common to both input and output. Its derived classes 
(istream, ostream, iostream) specialize I/O with high-level formatting 
operations. The ios class is a base for istream, ostream, fstreambase, and 
strstreambase. 



Public data members 

The following three constants are used as the second parameter of the setf 
function: 

static const long adjustfield; //left I right I internal 
static const long basefield; // dec I oct I hex 
static const long floatfield; //scientific I fixed 

Stream seek direction: 

enum seek_dir { beg=0, cur=l, end=2 }; 
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ios class 



Stream operation mode. These can be logically ORed: 



enum openjnode { 

app, 

ate, 

in, 

out, 

binary, 

trunc, 

nocreate, 
noreplace, 

}; 



Append data — always write at end of file. 

Seek to end of file upon original open. 

Open for input (default for if streams). 

Open for output (default for ofstreams). 

Open file in binary mode. 

Discard contents if file exists (default if out is specified 

and neither ate nor app is specified). 

If file does not exist, open fails. 

If file exists, open for output fails unless ate or app is 

set. 



Format flags used with flags, setf, and unsetf member functions: 



enum { 
skipws, 
left, 
right, 
internal, 
dec, 
oct, 
hex, 

showbase, 
showpoint, 
uppercase, 
showpos, 
scientific, 

fixed, 
unitbuf, 
stdio, 
}; 



Skip whitespace on input. 

Left-adjust output. 

Right-adjust output. 

Pad after sign or base indicator. 

Decimal conversion. 

Octal conversion. 

Hexadecimal conversion. 

Show base indicator on output. 

Show decimal point for floating-point output. 

Uppercase hex output. 

Show '+' with positive integers. 

Suffix floating-point numbers with exponential (E) 

notation on output. 

Use fixed decimal point for floating-point numbers. 

Flush all streams after insertion. 

Flush stdout, stderr after insertion. 



Protected data members 



streambuf 


*bp; 


int 


x_fill; 


long 


x_flags; 


int 


x_precision; 



/ / The associated streambuf 

/ / Padding character of output 

/ / Formatting flag bits 

/ / Floating-point precision on output 
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ios class 



int 


state; 


ostream 


*x_tie; 


int 


x width 



// Current state of the streambuf 
// The tied ostream, if any 
// Field width on output 



Public constructor 



Constructor 



Constructor 



bad 



bitalloc 



clear 



eof 



fail 



fill 



fill 



flags 



ios (streambuf *) ; 

Associates a given streambuf with the stream. 

Protected constructor 



ios ( ) ; 

Constructs an ios object that has no corresponding streambuf. 

Public member functions 

int bad ( ) ; 

Nonzero if error occurred. 

static long bitalloc(); 

Acquires a new flag bit set. The return value can be used to set, clear, and 
test the flag. This is for user-defined formatting flags. 

void clear (int = 0) ; 

Sets the stream state to the given value. 

int eof ( ) ; 

Nonzero on end of file. 

int fail(); 

Nonzero if an operation failed. 

char fill() 

Returns the current fill character. 

char fill (char) ; 

Resets the fill character; returns the previous character. 

long flags ( ) ; 

Returns the current format flags. 
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ios class 



flags 

good 

precision 

precision 

rdbuf 

rdstate 
setf 

setf 

sync_with_stdio 
tie 



tie 



unsetf 



long flags (long) ; 

Sets the format flags to be identical to the given long; returns previous 
flags. Use flags(O) to set the default format. 

int good ( ) ; 

Nonzero if no state bits were set (that is, no errors appeared). 

int precision () ; 

Returns the current floating-point precision. 

int precision (int) ; 

Sets the floating-point precision; returns previous setting. 

streambuf * rdbuf ( ) ; 

Returns a pointer to this stream's assigned streambuf. 

int rdstate ( ) ; 

long setf (long) ; 

Sets the flags corresponding to those marked in the given long; returns 
previous settings. 

long setf (long _setbits, long _f ield) ; 

The bits corresponding to those marked in Jield are cleared, and then reset 
to be those marked in jsetbits. 

static void sync_with_stdio ( ) ; 

Mixes stdio files and iostreams. This should not be used for new code. 

ostream* tie() ; 

Returns the tied stream, or NULL if there is none. Tied streams are those 
that are connected such that when one is used, the other is affected. For 
example, cin and cout are tied; when cin is used, it flushes cout first. 

ostream* tie(ostream *out); 

Ties another stream to the output stream out and returns the previously 
tied stream. If the stream was not previously tied, tie returns NULL. 

When an input stream has characters to be consumed, or if an output 
stream needs more characters, the tied stream is first flushed automatically. 
By default, cin, cerr and clog are tied to cout. 

long unsetf (long f ) ; 
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ios class 



width 



width 



xalloc 



Clears the bits corresponding to /and returns a long that represents the 
previous settings. 

int width ( ) ; 

Returns the current width setting. 

int width (int) ; 

Sets the width as given; returns the previous width. 

static int xalloc () ; 

Returns an array index of previously unused words that can be used as 
user-defined formatting flags. 



Protected member functions 



init 



setstate 



void init (streambuf *); 
Provides the actual initialization. 

void setstate (int) ; 
Sets all status bits. 



iostream class 



iostream.h 



This class, derived from istream and ostream, is a mixture of its base classes, 
allowing both input and output on a stream. It is a base for [stream and 
strstream. 

Public constructor 

Constructor iostream (streambuf *); 

Associates a given streambuf with the stream. 



iostream_withassign class 



iostream.h 



This class is an iostream with an added assignment operator. 
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iostream_withassign class 



Public constructor 



Constructor iostream_withassign() ; 

Default constructor (calls iostream's constructor). 

Public member functions 



None (although the = operator is overloaded). 



istream class 



iostream.h 



Provides formatted and unformatted input from a streambuf. The » 
operator is overloaded for all fundamental types, as explained in the 
narrative at the beginning of the chapter. This ios class is a base for ifstream, 
iostream, istrstream, and istreamjwithassign. 

Public constructor 

Constructor istream ( streambuf *); 

Associates a given streambuf with the stream. 



Public member functions 



gcount 

get 

get 



int gcount ( ) ; 

Returns the number of characters last extracted. 

int get ( ) ; 

Extracts the next character or EOF. 

istream& get (char *buf, int len, char delim = ' \n'); 
istreamk get (signed char *buf, int len, char delim = '\n'); 
istream& get (unsigned char *buf, int len, char delim = '\n'); 

Extracts characters and stores them in buf until the delimiter, specified by 
delim, or end-of-file is encountered, or until (len - 1) bytes have been read. A 
terminating null is always placed in the output string; the delimiter never 
is. The delimiter remains in the stream. Fails only if no characters were 
extracted. 
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istream class 



get 

get 
getline 



ignore 
ipfx 

peek 

putback 

read 



seekg 
seekg 



The get function fails if it encounters the end of file before any characters 
are stored. On failure, get sets ioswfailbit. 

istreamk get (char &ch) ; 
istream& get (signed char &ch) ; 
istreamk get (unsigned char &ch) ; 

Extracts a single character into the ch reference. 

istream& get(streambuf &sbuf, char delim = '\n'); 

Extracts characters into the given sbuf reference until delim is encountered. 

istream& getline(char *buf, int len, char); 

istream& getline (signed char *buf, int len, char delim = '\n'); 

istreamk getline (unsigned char *buf, int len, char delim = '\n'); 

Same as get, except the delimiter is also extracted. Generally, the specified 
delim is not copied to buf. However, if the delimiter is encountered exactly 
when len characters have been extracted, delim is not extracted. 

istreamk ignore (int n = 1, int delim = EOF)'; 

Causes up to n characters in the input stream to be skipped; stops if delim is 
encountered. 

istream& ipfx (int n = 0); 

The ipfx function is called by input functions prior to fetching from an input 
stream. Functions that perform formatted input call ipfx(O); unformatted 
input functions call ipfx(l). 

int peek ( ) ; 

Returns next char without extraction. 

istreamk putback (char) ; 

Pushes back a character into the stream. 

istreamk read(char*, int); 
istreamk read(signed char*, int); 
istreamk read (unsigned char*, int); 

Extracts a given number of characters into an array. Use gcount for the 
number of characters actually extracted if an error occurred. 

istream& seekg (streampos pos); 

Moves to an absolute position in the input stream. 

istreamk seekg (streamoff offset, seek_dir dir) ; 
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istream class 

Moves offset number of bytes relative to the current position for the input 
stream. The offset is in the direction specified by dir following the 
definition: enum seek_dir {beg, cur, end); 

Use ostreamwseekp for positioning in an output stream. 

Use seekpos or seekoff for positioning in a stream buffer. 

tellg streampos tellgO; 

Returns the current stream position. On failure, tellg returns a negative 
number. 

Use ostream::tellp to find the position in an output stream. 

Protected member functions 

eatwhite void eatwhiteO; 

Extract consecutive whitespace. 

istream_withassign class iostream.h 

This class is an istream with an added assignment operator. 

Public constructor 

Constructor istream_withassign ( ) ; 

Default constructor (calls [stream's, constructor). 

Public member functions 

None (although the = operator is overloaded). 

istrstream class strstrea.h 

Provides input operations on a strstreambuf. This class is derived from 
strstreambase and istream. 
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istrstream class 



Public constructors 



Constructor 



Constructor 



istrstream (char *) ; 
istrstream(signed char *); . 
istrstream (unsigned char *); 

Each of the constructors above makes an istrstream with a specified string (a 
null character is never extracted). See "The three char types" in Chapter 1 
of the Programmer's Guide for a discussion of character types. 

istrstream(char *str, int n) ; 

istrsteamf signed char *str, int); \ 

istrstream (unsigned char *str, int); 

Each of the three constructors above makes an istrstream using up to n bytes 
of str. See "The three char types" in Chapter 1 of the Programmer's Guide for 
a discussion of character types. 



ofstream class 



fstream.h 



Provides input operations on afilebuf. This class is derived from fstreambase 
and ostream. 



Constructor 
Constructor 

Constructor 
Constructor 



Public constructors 

of stream (); 

Makes an ofstream that isn't attached to a file. 

ofstream (const char *name, int mode = ios::out, 
int prot = filebuf : .-openprot) ; 

Makes an ofstream, opens a file, and connects to it. 

ofstream (int fd) ; 

Makes an ofstream and connects to an open-file descriptor specified by fd. 

ofstream(int fd, char *buf, int len); 

Makes an ofstream connected to an open-file descriptor specified by fd. The 
buffer specified by buf of len is used by the ofstream. 
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ofstream class 



Public member functions 



open 



rdbuf 



void open (const char *name, int mode = ios::out, 
int prot = filebuf : :openprot) ; 

Opens a file for an ofstream. 

filebuf* rdbuf (); 
Returns the filebuf used. 



ostream class 



iostream.h 



Provides formatted and unformatted output to a streambuf. The « operator 
is overloaded for all fundamental types. This fos-based class is a base for 
constream, iostream, ofstream, ostrstream, and ostream_withassign. 

Public constructor 

Constructor ostream (streambuf *); 

Associates a given streambuf with the stream. 

Public member functions 



flush 



opfx 



osfx 



put 



ostream& flush () ; 
Flushes the stream. 

int opfx() ; 

The opfx function is called by output functions prior to inserting to an 
output stream, opfx returns if the ostream has a nonzero error state. 
Otherwise, opfx returns a nonzero value. 

void osfx() ; 

The osfx function performs post output operations. If ioswunitbuf is on, opfx 

flushes the ostream. On failure, opfx sets iosv. 

failbit. 

ostreamk put (unsigned char ch) ; 
ostream& put (char ch) ; 
ostream& put (signed char ch) ; 

Inserts the character. 
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ostream class 



seekp ostream& seekp (streampos) ; 

Moves to an absolute position (as returned from tellp). 

seekp ostreamk seekp (streamoff, seek_dir) ; 

Moves to a position relative to the current position, following the 
definition: enum seek_dir {beg, cur, end}; 

tellp streampos tellp (); 

Returns the current stream position. 

wr| t e ostreamk write(const signed char*, int n) ; 

ostream& write (const unsigned char*, int n) ; 
ostreamk write(const char*, int n) ; 

Inserts n characters (nulls included). 

ostream_withassign class iostream.h 

This class is an ostream with an added assignment operator. 

Public constructor 

Constructor ostream_withassign(); 

Default constructor (calls ostream's constructor). 

Public member functions 

None (although the = operator is overloaded). 

ostrstream class strstrea.h 

Provides output operations on a strstreambuf. This class is derived from 
strstreambase and ostream. 

Public constructors 

Constructor ostrstream(); 
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ostrstream class 



Makes a dynamic ostrstream. 

Constructor ostrstream (char *buf, int len, int mode = ios::out); 

ostrstream (signed char *buf, int len, int mode = ios::out); 
ostrstream (unsigned char *buf, int len, int mode = ios: rout); 

Each of the three constructors above makes a ostrstream with a specified 
len-byte buffer. If the file-opening mode is ios::app or iosr.ate, the get/put 
pointer is positioned at the null character of the string. See "The three char 
types" in Chapter 1 of the Programmer's Guide for a discussion of character 
types. 

Public member functions 



pcount 



str 



int pcount ( ) ; 

Returns the number of bytes currently stored in the buffer. 

char *str() ; 

Returns and freezes the buffer. You must deallocate it if it was dynamic. 



streambuf class 



iostream.h 



This is a base class for all other buffering classes. It provides a buffer 
interface between your data and storage areas such as memory or physical 
devices. The buffers created by streambuf axe referred to as get, put, and 
reserve areas. The contents are accessed and manipulated by pointers that 
point between characters. 

Buffering actions performed by streambuf axe rather primitive. Normally, 
applications gain access to buffers and buffering functions through a 
pointer to streambuf that is set by ios. Class ios provides a pointer to 
streambuf that provides a transparent access to buffer services for high-level 
classes. The high-level classes provide I/O formatting. 

Public constructors 



Constructor 



Constructor 



streambuf ( ) ; 

Creates an empty buffer object. 

streambuf (char *buf, int size); 
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streambuf class 



Constructs an empty buffer buf and sets up a reserve area for size number of 
bytes. 

Public member functions 



in_avail 
out_waiting 
sbumpc 
seekoff 



seekpos 

setbuf 

sgetc 

sgetn 

snextc 

sputbackc 

sputc 

sputn 



int in_avail() ; 

Returns the number of characters remaining in the input buffer. 

int out_waiting ( ) ; 

Returns the number of characters remaining in the output buffer. 

int sbumpc ( ) ; 

Returns the current character from the input buffer, then advances. 

virtual streampos seekoff (streamoff, ios: :seek_dir, 

int = (ios:: in | ios: : out); 

Moves the get and /or put pointer (the third argument determines which 
one or both) relative to the current position. 

virtual streampos seekpos (streampos, int = (ios:: in I ios: : out)); 

Moves the get or put pointer to an absolute position. 

virtual streambuf* setbuf (char *, int); 

Connects to a given buffer. 

int sgetc () ; 

Peeks at the next character in the input buffer. 

int sgetn(char*, int n) ; 

Gets the next n characters from the input buffer. 

int snextc ( ) ; 

Advances to and returns the next character from the input buffer. 

int sputbackc (char) ; 

Returns a character to input. 

int sputc (int) ; 

Puts one character into the output buffer. 

int sputn(const char*, int n) ; 

Puts n characters into the output buffer. 
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streambuf class 



stossc 



void stossc () ; 

Advances to the next character in the input buffer. 

Protected member functions 



allocate 

base 

blen 

eback 

ebuf 

egptr 

epptr 

gbump 

gptr 

pbase 

pbump 

pptr 



int allocate () ; 

Sets up a buffer area. 

char *base ( ) ; 

Returns the start of the buffer area. 

int blen() ? 

Returns the length of the buffer area. 

char *eback() ; 

Returns the base of the putback section of the get area. 

char *ebuf () ; 

Returns the end+1 of the buffer area. 

char *egptr() ; 

Returns the end+1 of the get area. 

char *epptr() ; 

Returns the end+1 of the put area. 

void gbump (int) ; 

Advances the get pointer. 

char *gptr ( ) ; 

Returns the next location in the get area. 

char *pbase ( ) ; 

Returns the start of the put area. 

void pbump (int) ; 

Advances the put pointer. 

char *pptr ( ) ; 

Returns the next location in the put area. 
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streambuf class 



setb 


void setb (char *, char *, int = 




Sets the buffer area. 


setg 


void setg (char *, char *, char *); 




Initializes the get pointers. 


setp 


void setp (char *, char *); 




Initializes the put pointers. 


unbuffered 


void unbuffered (int) ; 




Sets the buffering state. 


unbuffered 


int unbuffered () ; 




Returns nonzero if not buffered. 



strstreambase class 



strstrea.h 



Specializes ios to string streams. This class is entirely protected except for 
the member function strstreambase: :rdbuf. This class is a base for strstream, 
istrstream, and ostrstream. 

Public constructors 



Constructor 



Constructor 



strstreambase () ; 

Makes an empty strstreambase. 

strstreambase (char Vint, char *start); 

Makes an strstreambase with a specified buffer and starting position. 



Public member functions 



rdbuf 



strstreambuf * rdbuf ( ) ; 

Returns a pointer to the strstreambuf associated with this object. 



strstreambuf class 



strstrea.h 



Specializes streambuf Tor in-memory formatting. 
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strstreambuf class 



Public constructors 



Constructor 



Constructor 



Constructor 



Constructor 



strstreambuf ( ) ; 

Makes a dynamic strstreambuf. Memory will be dynamically allocated as 
needed. 

strstreambuf (void * (*)(long), void (*) (void *)); 

Makes a dynamic buffer with specified allocation and free functions. 

strstreambuf (int n) ; 

Makes a dynamic strstreambuf, initially allocating a buffer of at least n bytes. 

strstreambuf (char*, int, char *strt = 0) ; 

strstreambuf (signed char *, int, signed char *strt = 0); 

strstreambuf (unsigned char *, int, unsigned char *strt = 0); 

Each of the three constructors above makes a static strstreambuf with a 
specified buffer. If strt is not null, it delimits the buffer. See "The three char 
types" in Chapter 1 of the Programmer's Guide for a discussion of character 
types. 

Public member functions 



doallocate 



freeze 



overflow 



seekoff 



setbuf 



str 



virtual int doallocate () ; 
Performs low-level buffer allocation. 

void freeze (int = 1) ; 

If the input parameter is nonzero, disallows storing any characters in the 
buffer. Unfreeze by passing a zero. 

virtual int overflow ( int ) ; 

Flushes a buffer to its destination. Every derived class should define the 
actions to be taken. 

virtual streampos seekoff (streamoff, ios: :seek_dir, int); 

Moves the pointer relative to the current position. 

virtual streambuf* setbuf (char*, int); 

Specifies the buffer to use. 

char *str() ; 

Returns a pointer to the buffer and freezes it. 
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strstreambuf class 



sync 



underflow 



virtual int sync ( ) ; 

Establishes consistency between internal data structures and the external 
stream representation. 

virtual int underflow!); 

Makes input available. This is called when a character is requested and the 
strstreambuf is empty. Every derived class should define the actions to be 
taken. 



strstream class 



strstrea.h 



Provides for simultaneous input and output on a strstreambuf. This class is 
derived from strstreambase and iostream. 

Public constructors 

Constructor strstream(); 

Makes a dynamic strstream. 

Constructor strstream (char *buf, int sz, int mode); 

strstream (signed char *buf, int sz, int mode); 
strstream (unsigned char *buf, int sz, int mode); 

Each of the three constructors above makes a strstream with a specified sz- 
byte buffer. If mode is ios::app or ios::ate, the get/put pointer is positioned at 
the null character of the string. See "The three char types" in Chapter 1 of 
the Programmer's Guide for a discussion of character types. 

Public member function 



str 



char *str(); 

Returns and freezes the buffer. The user must deallocate it if it was 
dynamic. 
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6 



Persistent stream classes and 
macros 



To learn how to use 

the persistent 

streams library, see 

Chapter 7 in the 

Programmer's Guide. 



Borland support for persistent streams consists of a class hierarchy and 
macros to help you develop streamable objects. This chapter is a reference 
for these classes and macros. It alphabetically lists and describes all the 
public classes that support persistent objects. The class descriptions are 
followed by descriptions of the _ _DELTA macro and the streaming 
macros. The streaming macros are provided to simplify the declaration and 
definition of streamable classes. 



The persistent streams class hierarchy 



The persistent streams class hierarchy is shown in the following figure: 



Figure 6.1 

Streamable class 

hierarchy 



pstream 



A A A 



TStreamable 



ipstream 



opstream 



ifpstream 



fpbase 



ofpstream 



The gray arrows connecting TStreamableBase indicate that it is a friend class. 



Chapter 6, Persistent stream classes and macros 



335 



fpbase class 



f pbase class 



objstm.h 



Provides the basic operations common to all object file stream I/O. 

Constructors 

Constructor fpbase(); 

fpbase(const char _FAR *name, int omode, int prot = filebuf : :openprot) ; 

fpbase (int f) ; 

fpbase(int f, char _FAR *b, int len) ; 

Creates a buffered fpbase object. You can set the size and initial contents of 
the buffer with the len and b arguments. You can open a file and attach it to 
the stream by specifying the name, mode, and protection (prot) arguments, 
or by using the file descriptor, /. 

Public member functions 



attach 



close 



open 



rdbuf 



setbuf 



void attach (int f) ; 

Attaches the file with descriptor / to this stream if possible. Sets ios::state 
accordingly. 

void closed ; 

Closes the stream and associated file. 

void open(const char _FAR *name, int mode, int prot = filebuf : ropenprot) ; 

Opens the named file in the given mode (app, ate, in, out, binary, trunc, 
nocreate, noreplace) and protection. The opened file is attached to this 
stream. 

filebuf _FAR * rdbuf ( ) ; 

Returns a pointer to the current file buffer. 

void setbuf (char _FAR *buf, int len); 
Allocates a buffer of size len. 



ifpstream class 



objstrm.h 



Provides the base class for reading (extracting) streamable objects from file 
streams. 
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ifpstream class 



Public constructors 



Constructor ifpstream(); 

ifpstream(const char _FAR *name, int mode = ios::in, int prot = 

filebuf : :openprot) ; 
ifpstream (int f) ; 
ifpstream(int f, char _FAR *b, int len); 

Creates a buffered ifpstream object. You can set the size and initial contents 
of the buffer with the len and b arguments. You can open a file and attach it 
to the stream by specifying the name, mode, and protection arguments, or 
via the file descriptor, /. 



Public member functions 



open void open (const char _FAR *name, int mode = ios::in, int prot = 

filebuf : :openprot) ; 

Opens the named file in the given mode (app, ate, in, out, binary, trunc, 
nocreate, or noreplace) and protection. The default mode is in (input) with 
openprot protection. The opened file is attached to this stream. 

rdblif filebuf _FAR * rdbuf(); 

Returns a pointer to the current file buffer. 

ipstream class objstrm.h 

Provides the base class for reading (extracting) streamable objects. 

Public constructors 

Constructor ipstream (streambuf *buf ) ; 

Creates a buffered ipstream with the given buffer and sets the bp data 
member to buf. The state is set to 0. 

Public member functions 



find 



TStreamableBase _FAR * find(P_id_type Id); 
Returns a pointer to the object corresponding to Id. 
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ipstream class 



freadBytes 
freadString 



getVersion 
read Byte 
read Bytes 
readString 



readWord 



readWord16 



readWord 



registerObject 



void freadBytes ( void far *data, size_t sz ) ; 

Reads into the supplied far buffer (data) the number of bytes specified by sz. 

char * freadString () ; 

Reads a string from the stream. Determines the length of the string and 
allocates a far character array of the appropriate length. Reads the string 
into this array and returns a pointer to the string. The caller is expected to 
free the allocated memory block. 

char * freadString ( char far *buf, unsigned maxLen ); 

Reads a string from the stream into the supplied far buffer {buf). If the 
length of the string is greater than maxLen-1, reads nothing. Otherwise 
reads the string into the buffer and appends a null terminating byte. 

uint32 getVersion () const; 

Returns the object version number. 

uint8 readByte() ; . 

Returns the character at the current stream position. 

void readBytes(void _FAR *data, size_t sz); 

Reads sz bytes from current stream position, and writes them to data. 

char _FAR * readString ( ) ; 

char _FAR * readString (char _FAR *buf, unsigned maxLen); 

readStringO allocates a buffer large enough to contain the string at the 
current stream position. Reads the string from the stream into the buffer. 
The caller must free the buffer. 

readString(Pchar buf, unsigned maxLen) reads the string at the current stream 
position into the buffer specified by buf. Does not read more than maxLen 
bytes. 

uint32 readWord () ; 

Returns the 32-bit word at the current stream position. 

uintl6 readWordl6() ; 

Returns the 16-bit word at the current stream position. 

uint32 readWord32() ; 

Returns the 32-bit word at the current stream position. 

void registerObject (TStreamableBase * adr) ; 
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ipstream class 



seekg 



tellg 



Registers the object pointed to by adr. 

ipstream& seekg (streampos pos); 

ipstream& seekg (streamoff off, ios: :seek_dir) ; 

The first form moves the stream position to the absolute position given by 
pos. The second form moves to a position relative to the current position by 
an offset off (+ or -) starting at ios::seek_dir. ios::seek_dir can be set to beg 
(start of stream), cur (current stream position), or end (end of stream). 

streampos tellg () ; 

Returns the (absolute) current stream position. 



Protected constructors 



Constructor 



ipstream(); 

The protected form of the constructor does not initialize the buffer pointer 
bp. Use init to set the buffer and state. 

Protected member functions 



readData 



read Prefix 



readSuffix 



readVersion 



void _FAR * readData (const ObjectBuilder _FAR* ,TStreamableBase _FAR *& 
mem) ; 

Invokes the appropriate read function to read from the stream to the object 
pointed to by mem. If mem is 0, the appropriate build function is called first. 

See also: TStreamableClass, and the read and build member functions of each 
streamable class 

const ObjectBuilder _FAR * readPrefixO ; 

Returns the TStreamableClass object corresponding to the class name stored 
at the current position. 

void readSuffix() ; 

Reads and checks the final byte of an object's name field. 

See also: ipstream: ireadPrefix 

void readVersion () ; 

Sets the version number of the input stream. 
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ipstream class 



Operator » 



Friends 



friend 
friend 
friend 
friend 
friend 
friend 
friend 
friend 
friend 
friend 
friend 
friend 
friend 



ipstreamk 
ipstreamk 
ipstream& 
ipstreamk 
ipstream& 
ipstream& 
ipstreamk 
ipstream& 
ipstreamk 
ipstream& 
ipstream& 
ipstreamk 
ipstreamk 



operator » 
operator » 
operator » 
operator » 
operator » 
operator » 
operator » 
operator » 
operator » 
operator » 
operator » 
operator » 
operator » 



(ipstreamk ps, 
(ipstreamk ps, 
(ipstreamk ps, 
(ipstream& ps, 
(ipstreamk ps, 
(ipstream& ps, 
(ipstream& ps, 
(ipstream& ps, 
(ipstreamk ps, 
(ipstreamk ps, 
(ipstreamSc ps, 
(ipstreamk ps, 
(ipstreamk ps, 



signed char _FAR & ch) ; 
unsigned char _FAR & ch) ; 
signed short _FAR & sh) ; 
unsigned short _FAR & sh) ; 
signed int _FAR & i) ; 
unsigned int _FAR & i); 
signed long _FAR & 1); 
unsigned long _FAR & 1); 
float _FAR & f ) ; 
double _FAR & d) ; 
long double _FAR & d) ; 
TStreamableBase t); 
void *t) ; 



Extracts (reads) from the ipstream ps, to the given argument. A reference to 
the stream is returned, letting you chain » operations in the usual way. 
The data type of the argument determines how the read is performed. For 
example, reading a signed char is implemented using readByte. 



ofpstream class 



objstrm.h 



Provides the base class for writing (inserting) streamable objects to file 
streams. 

Public constructors 

Constructor ofpstream ()'; 

ofpstream (const char _FAR *name, int mode = ios::out, 

int prot = filebuf : :openprot) ; 
ofpstream (int f ) ; 
ofpstream(int f, char _FAR *b, int len) ; 

Creates a buffered ofpstream object. You can set the size and initial contents 
of the buffer with the len and b arguments. A file can be opened and 
attached to the stream by specifying the name, mode, and protection 
arguments, or by using the file descriptor, /. 
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ofpstream class 



Public member functions 



open 



rdbuf 



void open (char _FAR *name, int mode = ios::out, 
int prot = filebuf ::openprot) ; 

Opens the named file in the given mode (app, ate, in, out, binary, trunc, 
nocreate, or noreplace) and protection. The default mode is out (output) with 
openprot protection. The opened file is attached to this stream. 

filebuf _FAR * rdbuf (); 

Returns the current file buffer. 



opstream class 



objstrm.h 



opstream, a specialized derivative of pstream, is the base class for writing 
(inserting) streamable objects. 

Public constructors and destructor 

Constructor opstream ( streambuf _FAR *buf); 

This constructor creates a buffered opstream with the given buffer and sets 
the bp data member to buf. The state is set to 0. 

Destructor ~opstream(); 

Destroys the opstream object. 

See also: pstream::init 

Public member functions 



findObject 
findVB 
flush 
fwriteBytes 



P_id_type findObject (TStreamableBase _FAR *adr) ; 
Returns the type ID for the object pointed to by adr. 
P_id_type findVB (TStreamableBase _FAR *adr) ; 
Returns a pointer to the virtual base. 

opstream& flush () ; 
Flushes the stream. 

void fwriteBytes ( const void *data, size_t sz ); 
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opstream class 



fwriteString 
register-Object 
registerVB 
seekp 



tellp 

writeByte 

writeBytes 

writeObject 

writeObjectPtr 

writeString 

writeWord 

writeWord16 



Writes the specified number of bytes (sz) from the supplied far buffer (data) 
to the stream. 

void fwriteString ( const char *str ); 

Writes the specified far character string (str) to the stream. 

void registerObject(TStrearaableBase _FAR *adr) ; 

Registers the class of the object pointed to by adv. 

void registerVB (TStreamableBase _FAR *adr) ; 

Registers a virtual base class. 

opstreamk seekp (streampos pos); 

opstream& seekp (streamoff off,ios: :seek_dir) ; 

The first form moves the stream's current position to the absolute position 
given by pos. The second form moves to a position relative to the current 
position by an offset off (+ or -) starting at ios::seek_dir. ios::seek_dir can be set 
to beg (start of stream), cur (current stream position), or end (end of stream). 

streampos tellp () ; 

Returns the (absolute) current stream position. 

void writeByte (uint8 ch) ; 

Writes the byte ch to the stream. 

void writeBytes (const void *data, size_t sz); 
void writeBytes (const void far *data, size_t sz); 

Writes sz bytes from data buffer to the stream. 

void writeObject ( const TStreamableBase _BIDSFAR *t ) ; 

Writes the object that is pointed to by t to the output stream. 

void writeObjectPtr (const TStreamableBase *t); 

Writes the object pointer t to the output stream. 

void writeString (const char _FAR *str) ; 

Writes str to the stream (together with a leading length byte). 

void writeWord (uint32 us); 

Writes the 32-bit word us to the stream. 

void writeWordl6(uintl6 us); 

Writes the 16-bit word us to the stream. 
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opstream class 



writeWord32 void writeWord32 (uint32 us); 

Writes the 32-bit word us to the stream. 

Protected constructors 



Constructor opstreamO; 

This protected form of the constructor does not initialize the buffer pointer 
bp. Use init to set the buffer and state. 

Protected member functions 



writeData 



writePrefix 



writeSuffix 



void writeData (TStreamableBase *t); 

Writes data to the stream by calling the appropriate class's write member 
function for the object being written. 

See also: TStreamableBase and the write functions in the streamable classes 

void writePrefix (const TStreamableBase *t); 

Writes the class name prefix to the stream. The « operator uses this 
function to write a prefix and suffix around the data written with writeData. 
The prefix/suffix is used to ensure type-safe stream I/O. 

See also: ipstream:readPrefix 

void writeSuffix (const TStreamableBase *t); 

Writes the class name suffix to the stream. The « operator uses this 
function to write a prefix and suffix around the data written with writeData. 
The prefix/suffix is used to ensure type-safe stream I/O. 

See also: ipstream:readPrefix 



Operator « 



Friends 



friend opstreamk operator 


« 


opstream& 


ps, 


signed char ch) ; 


friend opstreamk operator 


« 


opstreamk 


ps, 


unsigned char ch) ;, 


friend opstreamk operator 


« 


(opstream& 


ps, 


signed short sh) ; 


friend opstream& operator 


« 


opstream& 


ps, 


unsigned short sh) ; 


friend opstream& operator 


« 


opstreamk 


ps, 


signed int i) ; 


friend opstreamk operator 


« 


opstreamk 


ps, 


unsigned int i) ; 


friend opstream& operator 


<< 


opstreamk 


ps, 


signed long 1) ; 
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opstream class 



friend opstream& operator « (opstreamk ps, unsigned long 1); 

friend opstreamk operator « (opstream& ps, float f); 

friend opstream& operator « (opstreamk ps, double d) ; 

friend opstreamk operator « (opstream& ps, long double d) ; 

friend opstream& operator « (opstreamk ps, TStreamableBasek t) ; 

Inserts (writes) the given argument to the given ipstream object. The data 
type of the argument determines the form of write operation employed. 



pstream class 



objstrm.h 



pstream is the base class for handling streamable objects. 

Type definitions 

PointerTypes ' e num PointerTypes{ptNull, ptlndexed, ptObject}; 

Enumerates object pointer types. 

Public constructors and destructor 



Constructor pstream (streambuf _FAR *buf); 

This constructor creates a buffered pstream with the given buffer and sets 
the bp data member to buf. The state is set to 0. 

Destructor virtual -pstream () ; 

Destroys the pstream object. 



Public member functions 



bad 



clear 



eof 



int bad() const; 

Returns nonzero if an error occurs. 

void clear (int aState =0); 

Set the stream state to the given value (defaults to 0). 

int eof() const; 

Returns nonzero on end of stream. 
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pstream class 



fail 

good 

rdbuf 

rdstate 



Operator void *() 



Operator ! () 



bp 



state 



Constructor 



int fail() const; 

Returns nonzero if a stream operation fails. 

int good() const; 

Returns nonzero if no state bits are set (that is, if no errors occurred). 

streambuf _FAR * rdbuf () const; 

Returns the pb pointer to this stream's assigned buffer. 

See also: pstreamr.pb 

int rdstate () const; 

Returns the current state value. 

Operators 

operator void *() const; 

Overloads the pointer-to-uo/rf cast operator. Returns if the operation has 
failed (that is, if pstreamr.fail returned nonzero); otherwise, returns nonzero. 

See also: pstreamr.fail 

int operator ! () const; 

Overloads the NOT operator. Returns the value returned by pstream:: fail. 

See also: pstreamr.fail 

Protected data members 

streambuf _FAR *bp; 

Pointer to the stream buffer. 

int state; 

Format state flags. Use rdstate to access the current state. 

See also: pstream: -.rdstate 

Protected constructors 

pstream () ; 
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This form of the constructor does not initialize the buffer pointer bp. Use 
init and setstate to set the buffer and state. 



Protected member functions 



init 



setstate 



void init(strearabuf _FAR *sbp) ; 

Initializes the stream: sets state to and bp to sbp. 

void setstate (int b) ; 

Updates the state data member with state 1= (b & OxFF), 



TStreamableBase class 



objstrm.h 



class _EXPCLASS TStreamableBase : public TCastable 

Classes that inherit from TStreamableBase are known as streamable classes, 
meaning their objects can be written to and read from streams. If you want 
to develop your own streamable classes, you should make sure that 
TStreamableBase is somewhere in their ancestry. Using an existing 
streamable class as a base, of course, is an obvious way of achieving this. 
Don't be afraid to use multiple inheritance to derive a class from 
TStreamableBase if your class must also fit into an existing class hierarchy. 



Typejd 



Type definitions 



typedef const char *Type_id; 
Describes type identifiers. 



Public destructor 



Destructor 



virtual -TStreamableBase () {}; 
Destroys the TStreamableBase object. 



Public member functions 



CastablelD 



virtual Type_id CastablelD () const = 0; 
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TStreamableBase class 



Provides support for typesafe downcasting. Returns a string containing the 
type name. 



FindBase 



virtual void *FindBase( Type_id id ) const; 
Returns a pointer to the base class. 
MostDerived virtual void *MostDerived() const = 0; 

Returns a void pointer to the actual streamed object. 

TStreamableClass class streambl.h 

Used by the private database class and pstream in streamable class 
registration. 

Public constructor 

Constructor ' TStreamableClass (const char *n, BUILDER b, int d=NoDelta, Moduleld 

mid=GetModuleId()) ; 

Creates a TStreamableClass object with the given name (n) and the given 
builder function (b), then registers the type. Each streamable class, for 
example TClassname, has a build member function of type BUILDER. For 
type-safe object-stream I/O, the stream manager needs to access the names 
and the type information for each class. To ensure that the appropriate 
functions are linked into any application using the stream manager, you 
must provide a reference such as: 

TStreamableClass RegClassName; 

where TClassName is the name of the class for which objects need to be 
streamed. (Note that RegClassName is a single identifier.) This not only 
registers TClassName (telling the stream manager which build function to 
use), it also automatically registers any dependent classes. You can register 
a class more than once without any harm or overhead. 

Invoke this function to provide raw memory of the correct size into which 
an object of the specified class can be read. Because the build procedure 
invokes a special constructor for the class, all virtual table pointers are 
initialized correctly. 
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The distance, in bytes, between the base of the streamable object and the 
beginning of the TStreamableBase component of the object is d. Calculate d 
by using the DELTA macro. For example, 

TStreamableClass RegTClassName = TStreamableClass ("TClassName", 
TClassName:: build, DELTA(TClassName) ) ; 

See also: TStreamableBase, ipstream, opstream 

Friends 



The classes opstream and ipstream are friends of TStreamableClass. 



TStreamer class 



objstrm.h 



class _BIDSCLASS _RTTI TStreamer 
Base class for all streamable objects. 

Public member functions 



GetObject 



TStreamableBase *GetObject() const 

Returns the address of the TStreamableBase component of the streamable 
object. 



Protected constructors 

Constructor TStreamer ( TStreamableBase *obj ) 

Constructs the TStreamer object, and initializes the streamable object 
pointer. 

Protected member functions 



Read 



StreamableName 



virtual void *Read( ipstreamk, uint32 ) const = 0; 

This pure virtual member function must be redefined for every streamable 
class. It must read the necessary data members for the streamable class 
from the supplied ipstream. 

virtual const char *StreamableName() const = 0; 
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This pure virtual member function must be redefined for every streamable 
class. StreamableName returns the name of the streamable class, which is 
used by the stream manager to register the streamable class. The name 
returned must be a O-terminated string. 

Write virtual void Write ( opstreamk ) const = 0; 

This pure virtual function must be redefined for every streamable class. It 
must write the necessary streamable class data members to the supplied 
opstream object. Write is usually implemented by calling the base class's 
Write (if any), and then inserting any additional data members for the 
derived class. 



_ _DELTA macro streambl.h 

ttdefine _DELTA( d ) (FP_0FF( (TStreamable *) (d *)1)-1) 

Calculates the distance, in bytes, between the base of the streamable object 
and the beginning of the TStreamableBase component of the object. 

DECLARE_STREAMABLE macro objstrm.h 

DECLARE_STREAMABLE(exp, els, ver) 

The DECLARE_STREAMABLE macro is used within a class definition to 
add the members that are needed for streaming. Because it contains access 
specifiers, it should be followed by an access specifier or be used at the end 
of the class definition. The first parameter should be a macro, which in turn 

should conditionally expand to either import or export, depending on 

whether or not the class is to be imported or exported from a DLL. The 
second parameter is the streamable class name. The third parameter is the 
object version number. DECLARE_STREAMABLE is defined as follows: 

ttdefine DECLARE_STREAMABLE(exp, els, ver ) \ 

DECLARE_CASTABLE ^ \ 

DECLARE_STREAMER(exp, els, ver ); \ 

DECLARE_STREAMABLE_OPS ( els ); \ 
DECLARE_STREAMABLE_CTOR( els ) 

See also: Chapter 9 in the Programmer's Guide 
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DECLARE_STREAMABLE_FROM_BASE macro objstrm.h 

DECLARE_STREAMABLE_FROM_BASE(exp, els, ver) 

DECLARE_STREAMABLE_FROM_BASE is used in the same way as 
DECLARE_STREAMABLE; it should be used when the class being defined 
can be written and read using Read and Write functions defined in its base 
class without change. This usually occurs when a derived class overrides 
virtual functions in its base or provides different constructors, but does not 
add any data members. (If you used DECLARE_STREAMABLE in this 
situation, you would have to write Read and Write functions that merely 
called the base's Read and Write functions. Using 
DECLARE_STREAMABLE_FROM_BASE prevents this.) 

DECLARE_STREAMABLE_FROM_BASE is defined as follows: 

#define DECLARE_STREAMABLE_FROM_BASE ( els, base, ver ) \ 

DECLARE_CASTABLE \ 

- DECLARE_STREAMER_FROM_BASE(exp, els, base, ver ) ; \ 

DECLARE_STREAMABLE_OPS ( els ) ; \ 

DECLARE_STREAMABLE_CTOR( els. ) 

DECLARE_ABSTRACT_STREAMABLE macro objstrm.h 

DECLARE_ABSTRACT_STREAMABLE(exp, els, ver) 

This macro is used in an abstract class. DECLARE_STREAMABLE doesn't 
work with an abstract class because an abstract class can never be 
instantiated, and the code that attempts to instantiate the object (Build) 
causes compiler errors. This macro expands to DECLARE_CASTABLE, 
DECLARE_ABSTRACT_STREAMER, DECLARE_STREAMABLE_OPS, 
and DECLARE_STREAMABLE_CTOR. 

DECLARE_STREAMER macro objstrm.h 

DECLARE_STREAMER(exp, els, ver ) 

This macro defines a nested class within your streamable class; it contains 
the core of the streaming code. DECLARE_STREAMER declares the Read 
and Write function declarations, whose definitions you must provide, and 
the Build function that calls the TStreamableClass constructor. See 
DECLARE_STREAMABLE for an explanation of the parameters. 
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DECLARE_STREAMER_FROM_BASE macro objstrm.h 

DECLARE_STREAMER_FROM_BASE ( exp, els, base ) 

This macro is used by DECLARE_STREAMABLE_FROM_BASE. It declares 
a nested Streamer class without the Read and Write functions. See 
DECLARE_STREAMABLE for a description of the parameters. 

DECLARE_ABSTRACT_STREAMER macro objstrm.h 

define DECLARE_ABSTRACT_STREAMER ( exp, els, ver ) 

This macro is used by DECLARE_ABSTRACT_STREAMABLE. It declares a 
nested Streamer class without the Build function. See 
DECLARE_STREAMABLE for an explanation of the parameters. 

DECLARE_CASTABLE macro objstrm.h 

DECLARE_CASTABLE 

This macro provides declarations that provide a rudimentary typesafe 
downcast mechanism. This is useful for compilers that don't support run- 
time type information. 

DECLARE_STREAMABLE_OPS macro objstrm.h 

DECLARE_STREAMABLE_OPS ( C 1 s ) 

Declares the inserters and extractors. For template classes, 
DECLARE_STRE AMABLE_OPS must use c las s< . . . > as the macro 
argument; other DECLARES take only the class name. 

DECLARE_STREAMABLE_CTOR macro objstrm.h 

DECLARE_STREAMABLE_CTOR ( els ) 

Declares the constructor called by the Streamerr.Build function. 
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IMPLEMENT_STREAMABLE macros objstrm.h 

IMPLEMENT_STREAMABLE ( els ) 

IMPLEMENT_STREAMABLEl(cls, basel) 

IMPLEMENT_STREAMABLE2(cls, basel, base2) 

IMPLEMENT_STREAMABLE3(cls, basel, base2, base3) 

IMPLEMENT_STREAMABLE4(cls, basel, base2, base3, base4) . 

IMPLEMENT_STREAMABLE5,(cls, basel, base2, base3, base4, base5) 

The IMPLEMENT_STREAMABLE macros generate the registration object 
for the class via IMPLEMENT_STREAMABLE_CLASS, and generate the 
various member functions that are needed for a streamable class via 
IMPLEMENT_ABSTRACT_STREAMABLE. 

IMPLEMENT_STREAMABLE is used when the class has no base classes 
other than TStreamableBase. Its only parameter is the name of the class. 
The numbered versions (IMPLEMENT_STREAMABLE1, 
IMPLEMENT_STREAMABLE2 / and so on) are for classes that have bases. 
Each base class, including all virtual bases, must be listed in the 
IMPLEMENT_STREAMABLE macro invocation. 

The individual components comprising these macros can be used 
separately for special situations, such for as custom constructors. 

IMPLEMENT_STREAMABLE_CLASS macro objstrm.h 

IMPLEMENT_STREAMABLE_CLASS (els) 
Constructs a TStreamableClass class instance. 

IMPLEMENT_STREAMABLE_CTOR macros objstrm.h 

IMPLEMENT_STREAMABLE_CTOR ( cl S ) 

IMPLEMENT_STREAMABLE_CTORl(cls, basel) 

IMPLEMENT_STREAMABLE_CT0R2(cls, basel, base2) 

IMPLEMENT_STREAMABLE_CT0R3(cls, basel, base2, base3) 

IMPLEMENT_STREAMABLE_CT0R4(cls, basel, base2, base3, base4) 

IMPLEMENT_STREAMABLE_CT0R5(cls, basel, base2, base3, base4, base5) 

Defines the constructor called by the Build function. All base classes must 
be listed in the appropriate macro. 
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IMPLEMENT STREAMABLE POINTER macro 



objstrm.h 



IMPLEMENT_STREAMABLE_POINTER ( els ) 

Creates the instance pointer extraction operator (»). 



IMPLEMENT CASTABLE ID macro 



objstrm.h 



IMPLEMENT_CASTABLE_ID ( els ) 

Sets the typesafe downcast identifier. 



IMPLEMENT CASTABLE macros 



objstrm.h 



IMPLEMENT_CASTABLE ( els ) 
IMPLEMENT_CASTABLE1 ( els 
IMPLEMENT_CASTABLE2 ( els 
IMPLEMENT_CASTABLE3 ( els 
IMPLEMENT_CASTABLE4 ( els 
IMPLEMENTS ASTABLE 5 ( els 

These macros implement code that supports the typesafe downcast 
mechanism. 



IMPLEMENT STREAMER macro 



objstrm.h 



IMPLEMENT_STREAMER( els ) 
Defines the Streamer constructor. 



IMPLEMENT ABSTRACT STREAMABLE macros 



objstrm.h 



IMPLEMENT_ABSTRACT_STREAMABLE ( els ) 
IMPLEMENT_ABSTRACT_STREAMABLE1 ( els 
IMPLEMENT_ABSTRACT_STREAMABLE2 ( els 
IMPLEMENT_ABSTRACT_STREAMABLE3 ( els 
IMPLEMENT_ABSTRACT_STREAMABLE4 ( els 
IMPLEMENT ABSTRACT STREAMABLE5( els 
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IMPLEMENT ABSTRACT STREAMABLE macros 



This macro expands to IMPLEMENT_STREAMER (which defines the 
Streamer constructor), IMPLEMENT_STREAMABLE_CTOR (which defines 
the TStreamableClass constructor), and 

IMPLEMENT_STREAMABLE_POINTER (which defines the instance 
pointer extraction operator). 

IMPLEMENT_STREAMABLE_FROM_BASE macro objstrm.h 

IMPLEMENT_STREAMABLE_FROM_BASE ( els, basel ) 

This macro expands to IMPLEMENT_STREAMABLE_CLASS (which 
constructs a TStreamableClass instance), 

IMPLEMENT_STREAMABLE_CTORl (which defines a one base class 
constructor that is called by Build), and 

IMPLEMENT_STREAMABLE_POINTER (which defines the instance 
pointer extraction operator). 
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See Chapter 7 in the This chapter is a reference guide to the Borland C++ container classes. Each 

Programmers Guide container class belongs to one of the following; groups, which are listed here 

for information on . t1 L , . . L ,° , ,.., oo r ' 

using containers with their associated header-file names. 



i Array (arrays.h) 

i Association (assoc.h) 

i Bag (bags.h) 

i Binary tree (binimp.h) 

i Dequeue (deques.h) 

i Dictionary (dict.h) 

i Double-linked list (dlistimp.h) 



i Hash table (hashimp.h) 
i List (listimp.h) 
i Queue (queues .h) 
i Set (sets.h) 
i Stack (stacks .h) 
i Vector (vectimp.h) 



TMArrayAsVector template 



arrays.h 



TMArrayAsVector implements a managed array of objects of type T, using a 
vector as the underlying implementation. It requires an == operator for 
type T. 



CondFunc 



IterFunc 



Type definitions 



typedef int ( *CondFunc) (const T &, void *); 

Function type used as a parameter to FirstThat and LastThat member 
functions. 

typedef void. ( *IterFunc) (T &, void *); . 

Function type used as a parameter to the ForEach member function. 



Public constructors 



Constructor 



TMArrayAsVector ( int upper, int lower ="0, int delta = ) 
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Creates an array with an upper bound of upper, a lower bound of lower, and 
a growth delta of delta. 

Public member functions 



Add 



AddAt 



ArraySize 
Destroy 



Detach 



FirstThat 



int Add( const T& t ) . 

Adds a T object at the next available index at the end of an array. Adding 
an element beyond the upper bound leads to an overflow condition. If 
overflow occurs and delta is nonzero, the array is expanded (by sufficient 
multiples of delta bytes) to accommodate the addition. If delta is zero, Add 
fails. Add returns if it couldn't add the object. 

int AddAt ( const T& t, int loc ) 

Adds a T object at the specified index. If that index is occupied, it moves the 
object up to make room for the added object. If loc is beyond the upper 
bound, the array is expanded if delta (see the constructor) is nonzero. If delta 
is zero, attempting to AddAt beyond the upper bound gives an error. 

unsigned ArraySize () const 

Returns the current number of cells allocated. 

int Destroy ( int i ) 

Removes the object at the given index. The object will be destroyed. 

int Destroy ( const T& t ) 

Removes the given object and destroys it. 

int Detach( int loc, TShouldDelete: -.DeleteType dt ^TShouldDelete: :NoDelete 

int Detach ( const T& t, TShouldDelete: : DeleteType dt = 
TShouldDelete : .-NoDelete ) 

The first version removes the object at loc; the second version removes the 
first object that compares equal to the specified object. The value of dt and 
the current ownership setting determine whether the object itself will be 
deleted. DeleteType is defined in the base class TShouldDelete as 
enum { NoDelete, DefDelete, Delete }. The default value of dt, NoDelete, 
means that the object will not be deleted regardless of ownership. With dt 
set to Delete, the object will be deleted regardless of ownership. If dt is set to 
DefDelete, the object will be deleted only if the array owns its elements. 

See also: TShouldDeleter.ownsElements 

T *FirstThat(CondFunc, void *args ) const 
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Flush 



ForEach 



Returns a pointer to the first object in the array that satisfies a given 
condition. You supply a test-function pointer / that returns true for a certain 
condition. You can pass arbitrary arguments via args. Returns if no object 
in the array meets the condition. 

See also: LastThat 

void Flush( TShouldDelete::DeleteType dt = TShouldDelete: .-DefDelete ) 

Removes all elements from the array without destroying the array. The 
value of dt determines whether the elements themselves are destroyed. By 
default, the ownership status of the array determines their fate, as 
explained in the Detach member function. You can also set dt to Delete and 
NoDelete. 

See also: Detach 

void ForEach (IterFunc, void *args ) 

ForEach creates an internal iterator to execute the given function for each 
element in the array. The args argument lets you pass arbitrary data to this 
function. 



GetltemslnContainer unsigned GetltemsInContainerO const 



HasMember 



IsEmpty 



IsFull 



LastThat 



LowerBound 



Returns the number of items in the array, as distinguished from ArraySize, 
which returns the size of the array. 

int HasMember ( const T& t ) const 

Returns 1 if the given object is found in the array; otherwise returns 0. 

int IsEmpty () const 

Returns 1 if the array contains no elements; otherwise returns 0. 

int IsFull () const 

Returns 1 if the array is full; otherwise returns 0. The array is full if delta is 
not equal to and if the number of items in the container equals the value 
returned by ArraySize. 

T *LastThat( int ( * f) (const T &, void *), void *args ) const 

Returns a pointer to the last object in the array that satisfies a given 
condition. You supply a test function pointer, /, that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. Note that LastThat creates its own 
internal iterator, so you can treat it as a "search" function. 

See also: FirstThat, ForEach 

int LowerBound () const 
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Returns the array's lowerbound. 
UpperBound j. nt upperBoundO const 

Returns the array's current upperbound. 



Protected member functions 



BoundBase { n i BoundBase( unsigned loc ) const 

Boundbase adjust vectors, which are zero-based, to arrays, which aren't 
zero-based. See ZeroBase. 

Fi^ int Find( const T& t ) const 

Finds the specified object and returns the object's index; otherwise returns 
INTJVIAX. 

void Grow( int loc ) 

Increases the size of the array, in either direction, so that loc is a valid index. 

void InsertEntry( int loc ) 

Creates an object and inserts it at loc, moving entries above loc up by one. 

T ItemAt ( int i ) const . 

Returns a copy of the object stored at location /. 

int Reallocate ( unsigned sz, unsigned offset = ) 

If delta (see the constructor) is zero, reallocate returns 0. Otherwise, reallocate 
tries to create a new array of size sz (adjusted upwards to the nearest 
multiple of delta). The existing array is copied to the expanded array and 
then deleted. In an array of pointers, the entries are zeroed for each unused 
element. In an array of objects, the default constructor is invoked for each 
unused element, offset is the location in the new vector where the first 
element of the old vector should be copied. This is needed when the array 
has to be extended downward. 

RemoveEntry vo id RemoveEntry( int loc ) 

Removes element at the loc index into the array, and reduces the array by 
one element. Elements from index (loc + 1) upward are copied to positions 
loc, (loc + 1), and so on. The original element at loc is lost. 

SetData vo id SetData( int loc, const T& t ) 

The given t replaces the existing element at the index loc. 

ZeroBase unsigned ZeroBase ( int loc ) const 



Grow 



InsertEntry 



ItemAt 



Reallocate 
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Returns the location relative to lowerbound (loc - lowerbound). 

Operators 

operator [] T& operator []( int loc ) 

T& operator [] ( int loc ) const 

Returns a reference to the element at the location specified by loc. the 
non-const version resizes the array if it's necessary to make loc a valid 
index. The const throws an exception in the debugging version on an 
attempt to index out of bounds. 



TMArrayAsVectorlterator template 



arrays.h 



Implements an iterator object to traverse TMArrayAsVector objects. 



Public constructors 



Constructor 



TMArrayAsVectorlterator ( const TMArrayAsVector<T,Alloc> & a ) 
Creates an iterator object to traverse TMArrayAsVector objects. 



Public member functions 



Current 



Restart 



Const T& Current ( ) ; 

Returns the current object. 

void Restart ( ) ; 

void. Restart ( unsigned start, unsigned stop ); 

Restarts iteration from the beginning, or over the specified range. 



operator ++ 



Operators 



Const T& operator ++(int); 

Moves to the next object, and returns the object that was current before the 
move (post-increment). 

Const T& operator ++ ( ) ; 
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Moves to the next object, and returns the object that was current after the 
move (pre-increment). 

operator int operator into const 

Converts the iterator to an integer value for testing if objects remain in the 
iterator. The iterator converts to if nothing remains in the iterator. 

TArrayAsVector template arrays.h 

TArrayAsVector implements an array of objects of type T, using a vector as 
the underlying implementation. T Standard Allocator is used to manage 
memory. See TMArrayAsVector on page 355 for members. 

Public constructors 

Constructor TArrayAsVector ( int upper, int lower = 0, int delta = ) : 

Creates an array with an upper bound of upper, a lower bound of lower, and 
a growth delta of delta. 

TArrayAsVectorlterator template arrays.h 

Implements an iterator object to traverse TArrayAsVector objects. See 
TMArrayAsVectorlterator on page 359 for members. 

Public constructors 

Constructor TArrayAsVectorlterator ( const TArrayAsVector<T> & a ) 

Creates an iterator object to traverse TArrayAsVector objects. 

TMIArrayAsVector template arrays.h 

Implements a managed, indirect array of objects of type T, using a vector as 
the underlying implementation. 

Type definitions 

CondFunc typedef int ( *CondFunc) (const T &, void *); 
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IterFunc 



Function type used as a parameter to FirstThat and LastThat member 
functions. 

typedef void ( *IterFunc) (T &, void *); 

Function type used as a parameter to ForEach member function. 



Public constructors 



Constructor 



Add 



AddAt 



ArraySize 
Destroy 



Detach 



TMIArrayAsVector ( int upper, int lower = 0, int delta = ) 

Creates an indirect array with an upper bound of upper, a lower bound of 
lower, and a growth delta of delta. 

Public member functions 

int Add( T *t ) 

Adds a pointer to a T object at the next available index at the end of an 
array. Adding an element beyond the upper bound leads to an overflow 
condition. If overflow occurs and delta is nonzero, the array is expanded (by 
sufficient multiples of delta bytes) to accommodate the addition. If delta is 
zero, Add fails. Add returns if the object couldn't be added. 

int AddAt ( T *t, int loc ) 

Adds a pointer to a T object at the specified index. If that index is occupied, 
it moves the object up to make room for the added object. If loc is beyond 
the upper bound, the array is expanded if delta (see the constructor) is 
nonzero. If delta is zero, attempting to AddAt beyond the upper bound gives 
an error. 

unsigned ArraySize () const 

Returns the current number of cells allocated. 

int Destroy! int i ) 

Removes the object at the given index. The object will be deleted. 

int Destroy ( T *t ) 

Removes the object pointed to by t and deletes it. 

int Detach ( T *t, DeleteType dt = NoDelete ) 
int Detach ( int loc, DeleteType dt = NoDelete ) 

The first version removes the object pointer at loc; the second version 
removes the specified pointer. The value of dt and the current ownership 
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setting determine whether the object itself will be deleted. DeleteType is 
defined in the base class TShouldDelete as enum { NoDelete, Def Delete, 
Delete } . The default value of dt, NoDelete, means that the object will not be 
deleted regardless of ownership. With dt set to Delete, the object will be 
deleted regardless of ownership. If dt is set to DefDelete, the object will be 
deleted only if the array owns its elements. 

See also: TShouldDelete::ownsElements 

FirstThat t *FirstThat(CondFunc, void *args ) const 

Returns a pointer to the first element in the array that satisfies a given 
condition. You supply a test-function pointer / that returns true for a certain 
condition. You can pass arbitrary arguments via args. Returns if no object 
in the container meets the condition. Note that FirstThat creates its own 
internal iterator, so you can treat it as a "search" function. 

See also: LastThat 

Find int Find( const T *t ) const 

Finds the first specified object pointer and returns the index. Returns 
INT_MAX not found. 

Flush vo id Flush ( DeleteType dt = DefDelete ) 

Removes all elements from the array without destroying the array. The 
value of dt determines whether the elements themselves are destroyed. By 
default, the ownership status of the array determines their fate, as 
explained in the Detach member function. You can also set dt to Delete and 
NoDelete. 

See also: Detach 

ForEach V0 - L ^ L ForEach(IterFunc, void *args ) 

ForEach creates an internal iterator to execute the given function for each 
element in the container. The args argument lets you pass arbitrary data to 
this function. 

GetltemslnContainer unsigned GetltemsInContainerO const 

Returns the number of items in the array. 

int HasMember( const T& t ) const 

Returns 1 if the given object is found in the array; otherwise returns 0. 

int IsEmptyO const 

Returns 1 if the array contains no elements; otherwise returns 0. 
IsFull int isFullO const 



HasMember 



IsEmpty 
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LastThat 



LowerBound 



UpperBound 



Returns 1 if the array is full; otherwise returns 0. 

T *LastThat( int ( * fj (const T &, void *), void *args ) const 

Returns a pointer to the last element in the array that satisfies a given 
condition. You supply a test function pointer, /, that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the container meets the condition. Note that LastThat creates its 
own internal iterator, so you can treat it as a "search" function. 

See also: FirstThat, ForEach 

int LowerBound () const 

Returns the array's lowerbound. 

int UpperBound () const 

Returns the array's current upperbound. 



Protected member functions 



BoundBase j. n t BoundBase( unsigned loc ) const 

Boundbase adjust vectors, which are zero-based, to arrays, which aren't 
zero-based. See ZeroBase. 

Grow void Grow( int loc ) 

Increases the size of the array, in either direction, so that loc is a valid index. 
InsertEntry void lnsertEntry( int loc ) 

Creates an object and inserts it at loc. 
ItemAt t ItemAt ( int i ) const 

Returns a copy of the object stored at location i. 

Reallocate i n t Reallocate ( unsigned sz, unsigned offset = ) 

If delta (see the constructor) is zero, reallocate returns 0. Otherwise, reallocate 
tries to create a new array of size sz (adjusted upward to the nearest 
multiple of delta). The existing array is copied to the expanded array and 
then deleted. In an array of pointers the entries are zeroed. In an array of 
objects the default constructor is invoked for each unused element, offset is 
the location in the new vector where the first element of the old vector 
should be copied. This is needed when the array has to be extended 
downward. 

RemoveEntry V oid RemoveEntry( int loc ) 



Chapter 7, The C++ container classes 



363 



Array containers 



Removes element at loc, and reduces the array by one element. Elements 
from index (loc + 1) upward are copied to positions loc, (loc + 1), and so on. 
The original element at loc is lost. 

SetData vo id SetData( int loc, const T& t ) 

The given t replaces the existing element at the index loc. 

SqueezeEntry vo id squeezeEntry ( unsigned loc ) 

Removes element at loc, and reduces the array by one element. Elements 
from index (loc + 1) upward are copied to positions loc, (loc + 1), and so on. 
The original element at loc is lost. 

ZeroBase unsigned ZeroBase( int loc ) const 

Returns the location relative to lowerbound (loc - lowerbound). 



operator [ ] 



Operators 



T * & operator [] ( int loc ) 

T *.& operator [] ( int loc ) const 

Returns a reference to the element at the location specified by loc. the 
non-const version resizes the array if it's necessary to make loc a valid 
index. The const throws an exception in the debugging version on an 
attempt to index out of bounds. 



TMIArrayAsVectorlterator template 



arrays.h 



Implements an iterator object to traverse TMIArrayAsVector objects. Based 
on TMVectorlteratorlmp. 

Public constructors 



Constructor 



TMIArrayAsVectorlterator ( const TMIArrayAsVector<T,Alloc> &a 
Creates an iterator object to traverse TMArrayAsVector objects. 



Public member functions 



Current 



T *Current(); 

Returns a pointer to the current object. 
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Restart void Restart ( ) ; 

void Restart ( unsigned start, unsigned sTop ); 

Restarts iteration from the beginning, or over the specified range. 

Operators 

operator ++ const T& operator ++(int); 

Moves to the next object, and returns the object that was current before the 
move (post-increment). 

Const T& operator ++(); 

Moves to the next object, and returns the object that was current after the 
move (pre-increment). 

TIArrayAsVector template arrays.h 

Implements an indirect array of objects of type T, using a vector as the 
underlying implementation. T Standard Allocator is used to manage memory. 
See TMIArrayAsVector on page 360 for members. 

Public constructors 

Constructor TIArrayAsVector ( int upper, int lower = 0, int delta = ) 

Creates an array with an upper bound of upper, a lower bound of lower, and 
a growth delta of delta. 

TIArrayAsVectorlterator template arrays.h 

Implements an iterator object to traverse TIArrayAsVector objects. Uses 
T Standard Allocator for memory management. See TMIArrayAsVectorlterator 
on page 364 for member functions and operators. 



Public constructors 



Constructor 



TIArrayAsVectorlterator ( const TTArrayAsVector<T> &a ) 
TMIArrayAs Vector Iterator<T, TStandardAllocator> (a) 
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Creates an iterator object to traverse TIArrayAsVector objects. 

TMSArrayAsVector template arrays.h 

Implements a sorted array of objects of type T, using a vector as the 
underlying implementation. With the exception of the AddAt member 
function, TMSArrayAsVector inherits its member functions and operators 
from TMArrayAsVector. See TMArrayAsVector on page 355 for members. 

Public constructors 

Constructor TMSArrayAsVector ( int upper, int lower = 0, int delta =0) 

Creates an array with an upper bound of upper, a lower bound of lower, and 
a growth delta of delta. It requires a < operator for type T. 

TMSArrayAsVectorlterator template arrays.h 

Implements an iterator object to traverse TMSArrayAsVector objects. See 
TMArrayAsVectorlterator on page 359 for members. 

Public constructors 

Constructor . TMSArrayAsVectorlterator ( const TMSArrayAsVector<T> & a ) : 

Creates an iterator object to traverse TSArrayAsVector objects. 

TSArrayAsVector template arrays.h 

Implements a sorted array of objects of type T, using a vector as the 
underlying implementation. With the exception of the AddAt member 
function, TSArrayAsVector inherits its member functions and operators 
from TMArrayAsVector. See TMArrayAsVector 355 for members. 

Public constructors 

Constructor TSArrayAsVector ( int upper, int lower =0, int delta = ) 
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Creates an array with an upper bound of upper, a lower bound of lower, and 
a growth delta of delta. It requires a < operator for type T. 

TSArrayAsVectorlterator template arrays.h 

Implements an iterator object to traverse TSArrayAsVector objects. See 
TMArrayAsVectorlterator on page 359 for members. 

Public constructors 

Constructor TSArrayAsVectorlterator ( const TSArrayAsVector<T> & a ) : 

Creates an iterator object to traverse TSArrayAsVector objects. 

TISArrayAs Vector template arrays.h 

Implements an indirect sorted array of objects of type T, using a vector as 
the underlying implementation. See TMIArrayAsVector on page 360 for 
members. 

Public constructors 

Constructor TISArrayAsVector ( int upper, int lower = 0, int delta = ) 

Creates an indirect array with an upper bound of upper, a lower bound of 
lower, and a growth delta of delta. 

TISArrayAsVectorlterator template arrays.h 

Implements an iterator object to traverse TISArrayAsVector objects. See 
TMArrayAsVectorlterator on page 359 for members. 

Public constructors 

Constructor TISArrayAsVectorIterator( const TISArrayAsVector<T> &a ) 

Creates an iterator object to traverse TISArrayAsVector objects. 
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TMISArrayAsVector template 



arrays.h 



Implements a managed, indirect sorted array of objects of type T, using a 
vector as the underlying implementation. See TMIArrayAsVector on page 
360 for members. 



Public constructors 



Constructor 



TMISArrayAsVector ( int upper, int lower =0, int delta = ) 

Creates an indirect array with an upper bound of upper, a lower bound of 
lower, and a growth delta of delta. 



TMDDAssociation template 



assoc.h 



Implements a managed association, binding a direct key (K) with a direct 
value (V) . Assumes that K has a HashValue member function, or that a 
global function with the following prototype exists: 

unsigned HashValue ( K & ); 

K also must have a valid == operator. Class A represents the user-supplied 
storage manager. 

Public constructors 

Constructor TMDDAssociation ( ) 

The default constructor. 

Constructor TMDDAssociation ( const K &k, const V &v ) 

Constructs an object that associates a copy of key object k with a copy of 
value object v. 

Public member functions 



HashValue 



Key 



unsigned HashValue () 

Returns the hash value for the key. 

K Key() 

Returns KeyData. 
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Value v Value () 

Returns ValueData. 



Operators 



operator == Tests equality between keys. 

TDDAssociation template assoc.h 

Standard association (direct key, direct value). Implements an association, 
binding a direct key (K) with a direct value (V). Assumes that K has a 
HashValue member function, or that a global function with the following 
prototype exists: 

unsigned HashValue ( K & ) ; 

K also must have a valid == operator. See TMDD 'Association on page 368 for 
members. 



Public constructors 



Constructor TDDAssociation () 

The default constructor. 
Constructor TDDAssociation ( const K &k, const V &v ) 

Constructs an object that associates key object k with value object v. 

TMDIAssociation template assoc.h 

Implements a managed association, binding a direct key (K) with a indirect 
value (V) . Assumes that K has a HashValue member function, or that a 
global function with the following prototype exists: 

unsigned HashValue ( K & ); 

K also must have a valid == operator. Class A represents the user-supplied 
storage manager. 
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Constructor 



Constructor 



Public constructors 



TMDIAssociationO 

The default constructor. 

TMDIAssociation( K k, V * v ) 

Constructs an object that associates key object k with value object v. 



Public member functions 



HashValue 



Key 



Value 



unsigned HashValue () 

Returns the hash value for the key. 

K Key() 

Returns the key. 

const V * Valued 

Returns a pointer to the data. 

Operators 



operator == i n t operator == (const TMDDAssociation<K,V,A> & a) 

Tests the equality between keys. 

TDIAssociation template 



assoc.h 



Implements an association, binding a direct key (K) with a indirect value 
(V). Assumes that K has a HashValue member function, or that a global 
function with the following prototype exists: 

unsigned HashValue ( K & ); 

K also must have a valid == operator. See TMDIAssociation on page 369 for 
members. 



Public constructors 



Constructor TDIAssociation ( ) 

The default constructor. 
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Constructor • TDIAssociation( K k, V * v ) 

Constructs an object that associates key object k with value object v. 



TMIDAssociation template 



assoc.h 



KeyData 



ValueData 



Implements a managed association, binding an indirect key (K) with a 
direct value (V) . Assumes that K has a HashValue member function, or that 
a global function with the following prototype exists: 

unsigned HashValue ( K & ); 

K also must have a valid == operator. Class A represents the user-supplied 
storage manager. 

Protected data members 

K KeyData; 

The key class passed into the template by the user. 

V ValueData; 

The value class passed into the template by the user. 

Public constructors 

TMIDAssociation () 

The default constructor. 

TMIDAssociation ( K *k f - V v ) 

Constructs an object that associates key object k with value object v. 

Public member functions 

unsigned HashValue () 

Returns the hash value for the key. 

const K * Key() 

Returns a pointer to the key. 

V Value () 



Constructor 



Constructor 



HashValue 



Key 



Value 
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Returns a copy of the data. 

Operators 



operator == j_ n t operator == (const TMIDAssociation<K,V,A> & a) 

Tests the equality between keys. 

TIDAssociation template assoc.h 

Implements an association, binding an indirect key (K) with a direct value 
(V) . Assumes that K has a HashValue member function, or that a global 
function with the following prototype exists: 

unsigned HashValue ( K & ); 

K also must have a valid == operator. See TMIDAssociation on page 371 for 
members. 

Public constructors 

Constructor TIDAssociation () 

The default constructor. 
Constructor TIDAssociation ( K * k, V v ) 

Constructs an object that associates key object *k with value object v. 

TMIIAssociation template assoc.h 

Implements a managed association, binding an indirect key (K) with an 
indirect value (V) . Assumes that K has a HashValue member function, or 
that a global function with the following prototype exists: 

unsigned HashValue ( K & ); 

K also must have a valid == operator. Class A represents the user-supplied 
storage manager. 



Public constructors 



Constructor 



TMIIAssociation) 
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Constructor 



HashValue 



Key 



Value 



operator == 



The default constructor. 

TMIIAssociation( K * k, V * v ) 

Constructs an object that associates key object *k with value object *v. 

Public member functions 

unsigned HashValue () 

Returns the hash value for the key. 

const K * Key() 

Returns a pointer to the key. 

V * Valued 

Returns a pointer to the data. 

Operators 

int operator == (const. TMIIAssociation<K,V,A> & a) 
Tests equality between keys. 



TIIAssociation template 



assoc.h 



Standard association (indirect key, indirect value). Implements an 
association, binding an indirect key (K) with an indirect value (V) . 
Assumes that K has a HashValue member function, or that a global function 
with the following prototype exists: 

unsigned HashValue ( K & ); 

K also must have a valid == operator. See TMIIAssociation on page 372 for 
members. 



Public constructors 



Constructor 



Constructor 



TIIAssociation () 

The default constructor. 

TIIAssociation ( K *k, V * v ) 

Constructs an object that associates key object *k with value object *v. 
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TMBagAsVector template 



bags.h 



Implements a managed bag of objects of type T, using a vector as the 
underlying implementation. Bags, unlike sets, can contain duplicate objects. 

Type definitions 



CondFunc 



IterFunc 



typedef int ( *CondFunc) (const T.&, void *); 

Function type used as a parameter to FirstThat and LastThat member 
functions. 

typedef void ( *IterFunc) (T &, void *); 

Function type used as a parameter to ForEach member function. 



Public constructors 



Constructor • TMBagAsVector ( unsigned sz = DEFAULT_BAG_SIZE ) 

Constructs a managed, empty bag. sz represents the number of items the 
bag can hold. 

Public member functions 



Add 



Detach 



FindMember 



int Add( const T& t ) ■ 

Adds the given object to the bag. 

int Detach ( const T& t, TShouldDelete: :DeleteType = 
TShouldDelete::NoDelete ) 

Removes the specified object. The value of dt and the current ownership 
setting determine whether the object itself will be deleted. DeleteType is 
defined in the base class TShouldDelete as enum { NoDelete, Def Delete, 
Delete } . The default value of dt, NoDelete, means that the object will not be 
deleted regardless of ownership. With dt set to Delete, the object will be 
deleted regardless of ownership. If dt is set to DefDelete, the object will be 
deleted only if the bag owns its elements. 

See also: TShouldDeleter.ownsElements 

T* FindMember ( const T& t ) const 

Returns a pointer to the given object if found; otherwise returns 0. 
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Flush void Flush ( TShouldDelete::DeleteType = TShouldDelete: :Def Delete ) 

Removes all the elements from the bag without destroying the bag. The 
value of dt determines whether the elements themselves are destroyed. By 
default, the ownership status of the bag determines their fate, as explained 
in the Detach member function. You can also set dt to Delete and NoDelete. 

See also: Detach 

ForEach void ForEach(IterFunc, void *args ) 

ForEach creates an internal iterator to execute the given function for each 
element in the bag. The args argument lets you pass arbitrary data to this 
function. 

GetltemslnContainer int GetltemsInContainerO const 

Returns the number of objects in the bag. 
HasMember int HasMember( const T& t ) const 

Returns 1 if the given object is found; otherwise returns 0. 
IsEmpty int isEmptyO const 

Returns 1 if the bag is empty; otherwise returns 0. 
IsFull int isFull() const 

Returns 0. 

Protected member functions 

Find virtual T *Find( const T& ) const; 

Returns a pointer to the given object if found; otherwise returns 0. 

TMBagAsVectorlterator template bags.h 

Implements an iterator object to traverse TMBagAsVector objects. See 
TM Array AsVectorlterator on page 359 members. 

Public constructors 

Constructor TMBagAsVectorlterator ( const TMBagAsVector<T,Alloc> & b ) . 

Constructs an object that iterates on TMBagAsVector objects. 
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TBagAsVector template bags.h 

Implements a bag of objects of type T, using a vector as the underlying 
implementation. TStandardAllocator is used to manage memory. See 
TMBagAsVector on page 374 for members. 

Public constructors 

Constructor TBagAsVector ( unsigned sz = DEFAULT_BAG_SIZE ) 

Constructs an empty bag. sz represents the number of items the bag can 
hold. 

TBagAsVectorlterator template bags.h 

Implements an iterator object to traverse TBagAsVector objects. 
TStandardAllocator is used to manage memory. See TMArrayAsVectorlterator 
on page 359 for members. 

Public constructors 

Constructor TBagAsVectorlterator ( const TBagAsVector<T> & h ) 

Constructs an object that iterates on TBagAsVector objects. 

TMIBagAsVector template bags.h 

Implements a managed bag of pointers to objects of type T, using a vector 
as the underlying implementation. 

Type definitions 

CondFunc typedef int ( *CondFunc) (const T &, void *); 

Function type used as a parameter to FirstThat and LastThat member 
functions. 

IterFunc typedef void ( *IterFunc) (T &, void *); 

Function type used as a parameter to ForEach member function. 
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Public constructors 



Constructor 



TMIBagAsVector ( unsigned sz = DEFAULT_BAG_SIZE ) 

Constructs an empty, managed, indirect bag. sz represents the initial 
number of slots allocated. 



Public member functions 



Add 



Detach 



FindMember 



FirstThat 



Flush 



ForEach 



int Add( T *t ) 

Adds the given object pointer to the bag. 

int Detach ( T *t, DeleteType dt = NoDelete ) 

Removes the specified object pointer. The value of dt and the current 
ownership setting determine whether the object itself will be deleted. 
DeleteType is defined in the base class TShouldDelete as enum { NoDelete, 
Def Delete, Delete }. The default value of dt, NoDelete, means that the object 
will not be deleted regardless of ownership. With dt set to Delete, the object 
will be deleted regardless of ownership. If dt is set to DefDelete, the object 
will only be deleted if the bag owns its elements. 

See also: TShouldDelete: :ownsElements 

T *FindMember( T *t )' const 

Returns a pointer to the object if found; otherwise returns 0. 

T *FirstThat(CondFunc, void *args ) const 
See: TMBagAsVectorr.FirstThat 

void Flush ( TShouldDelete:: DeleteType dt = TShouldDelete: : DefDelete ) 

Removes all the elements from the bag without destroying the bag. The 
value of dt determines whether the elements themselves are destroyed. By 
default, the ownership status of the bag determines their fate, as explained 
in the Detach member function. You can also set dt to Delete and NoDelete. 

See also: Detach 

void ForEach (IterFunc, void *args ) 

ForEach creates an internal iterator to execute the given function for each 
element in the bag. The args argument lets you pass arbitrary data to this 
function. 



GetltemslnContainer 



int GetltemslnContainer () const 
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HasMember 



IsEmpty 



IsFull 



LastThat 



Returns the number of objects in the bag. 

int HasMember ( const T& t ) const 

Returns 1 if the given object is found; otherwise returns 0. 

int isEmptyO const 

Returns 1 if the bag is empty; otherwise returns 0. 

int isFullO const 
Returns 0. 

T *LastThat(CondFunc, void *args ) const 

Returns a pointer to the last object in the array that satisfies a given 
condition. You supply a test function pointer, /, that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. Note that LastThat creates its own 
internal iterator, so you can treat it as a "search" function. 



TMIBagAsVectorlterator template 



bags.h 



Implements an iterator object to traverse TMIBagAsVector objects. See 
TMArrayAsVectorlterator on page 359 for members. 

Public constructors 



Constructor 



TMIBagAsVectorlterator ( const TMIBagAsVector<T,Alloc> & s ) 
Constructs an object that iterates on TMIBagAsVector objects. 



TIBagAsVector template 



bags.h 



Implements a bag of pointers to objects of type T, using a vector as the 
underlying implementation. T Standard Allocator is used to manage memory. 
See TMIBagAsVector on page 376 for members. 

Public constructors 

Constructor TIBagAsVector( unsigned sz = DEFAULT_BAG_SIZE ) 

Constructs an empty, managed, indirect bag. sz represents the initial 
number of slots allocated. 
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TIBagAsVectorlterator template bags.h 

Implements an iterator object to traverse TIBagAsVector objects. 
TStandardAllocator is used to manage memory. See TMArrayAsVectorlterator 
on page 359 for members. 

Public constructors 

Constructor TIBagAsVectorlterator ( const TIBagAsVector<T> & s ) 

Constructs an object that iterates on TMIBagAsVector objects. 

TBinarySearchTreelmp template binimp.h 

Implements an unbalanced binary tree. Class T must have < and == 
operators, and must have a default constructor. 

Public member functions 

Add int Add( const T& t )■ 

Creates a new binary-tree node and inserts a copy of object t into it. 
Detach int Detach ( const T& t, int del = ) 

Removes the node containing item t from the tree. 
Find T * Find( const T& t ) const 

Returns a pointer to the node containing item t. 
Flush void Flush; (int del=0); 

Removes all items from the tree. 

ForEach vo i(j ForEach( IterFunc iter, void * args, IteratorOrder order = InOrder ) 

Creates an internal iterator that executes the given function iter for each 
item in the container. The args argument lets you pass arbitrary data to this 
function. 

GetltemslnContainer uns ig n ed GetltemsInContainerO; 

Returns the number of items in the tree. 

Parent::lsEmpty i nt isEmptyO; 
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Returns 1 if the tree is empty; otherwise returns 0. 



Protected member functions 



EqualTo virtual int EqualTo( BinNode *nl, BinNode *n2 ) 

Tests the equality between two nodes. 
LessThan virtual int LessThan( BinNode *nl, BinNode *n2 ) 

Tests if node nl is less than node n2. 
DeleteNode virtual void DeleteNode( BinNode *node, int del) 

Deletes node. The second parameter is ignored. 

TBinarySearchTreelteratorlmp template 

Implements an iterator that traverses TBinarySearchTreelmp objects. 



binimp.h 



Public constructors 



Constructor 



TBinarySearchTreelteratorlmp ( TBinarySearchTreeImp<T>& tree, 
TBinarySearchTreeBase: :IteratorOrder order = 

TBinarySearchTreeBase: :In0rder ) : TBinaryTreeExternallteratorBase ( tree, 
order ) , CurNode (static_cast<TBinaryNodeImp<T>*> (Next ( ) ) ) 

Constructs an iterator object that traverses a TBinarySearchTreelmp 
container. 



Public member functions 



Current 



Restart 



const T& Current () const 

Returns the current object. 

void Restart () 

Restarts iteration from the beginning of the tree. 



operator int 



Operators 



operator int() const 
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Converts the iterator to an integer value for testing if objects remain in the 
iterator. The iterator converts to if nothing remains in the iterator. 

operator ++ con st T& operator ++ ( int ) 

Moves to the next object in the tree, and returns the object that was current 
before the move (post-increment). 

const T& operator ++ () 

Moves to the next object, and returns the object that was current after the 
move (pre-increment). 



TIBinarySearchTreelmp template 



binimp.h 



Implements an indirect unbalanced binary tree. Class T must have < and == 
operators, and must have a default constructor. 

Public member functions 

Add int Add( T * t ) . 

Creates a new binary-tree node and inserts a pointer to object t into the tree. 

Detach i nt Detach ( T * t, int del = ) ' 

Removes the node containing item t from the tree. The item is deleted if del 
is 1. 

Find T * Find( T * t ) const 

Returns a pointer to the node containing *t. 

FiUSh void Flush; (int del=0); 

Removes all items from the tree. The are deleted if del is 1. If del is the 
items are not deleted. 

ForEach V oid ForEach( void ( *func) (T &, void *), void * args, IteratorOrder order 

= InOrder ) 

Creates an internal iterator that executes the given function / for each item 
in the container. The args argument lets you pass arbitrary data to this 
function. 

GetltemslnContainer ^signed GetltemsInContainerO ; 

Returns the number of items in the tree. 

Parent::lsEmpty i nt isEmptyO; 
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Returns 1 if the tree is empty; otherwise returns 0. 



Protected member functions 



EqualTo virtual int EqualTo ( BinNode *nl, BinNode *n2 ) 

Tests the equality between two nodes. 

LessThan virtual int £essThan( BinNode *nl, BinNode *n2 ) 

Tests if node nl is less than node n2. 

DeleteNode virtual void DeleteNodet BinNode *node, int del) 

Deletes node. The second parameter is ignored. 



TIBinarySearchTreelteratorlmp template 



binimp.h 



Implements an iterator that traverses TIBinarySearchTreelmp objects. 

Public constructors 



Constructor 



TIBinarySearchTreelteratorlmp ( TIBinarySearchTreeImp<T>& tree, 
TBinarySearchTreeBase: : IteratorOrder order = 
TBinarySearchTreeBase: :In0rder ) : 
TBinarySearchTreeIteratorImp<TVoidPointer> (tree, order) 

Constructs an iterator object that traverses a TIBinarySearchTreelmp 
container. 



Current 



Restart 



operator int 



Public member functions 



T *Current() const 

Returns a pointer to the current object. 

void Restart () 

Restarts iteration from the beginning of the tree. 

Operators 



operator int() const 
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Converts the iterator to an integer value for testing if objects remain in the 
iterator. The iterator converts to if nothing remains in the iterator. 

operator ++ ' T Operator ++ ( int i ) 

Moves to the next object in the tree, and returns a pointer to the object that 
was current before the move (post-increment). 

T *operator ++ () 

Moves to the next object, and returns a pointer to the object that was 
current after the move (pre-increment). 



TMDequeAsVector template 



deques.h 



Implements a managed dequeue of T objects, using a vector as the 
underlying implementation. 

Type definitions 



CondFunc 



IterFunc 



typedef int ( *CondFunc) (const T &, void *); ' 

Function type used as a parameter to FirstThat and LastThat member 
functions. 

typedef void ( *IterFunc) (T &, void *); 

Function type used as a parameter to ForEach member function. 



Public constructors 



Constructor -TMDequeAsVector ( unsigned max = DEFAULT_DEQUE_SIZE 

Constructs a dequeue of max size. 

Public member functions 



FirstThat 



T *FirstThat (CondFunc, void *args ) const; 

Returns a pointer to the first object in the dequeue that satisfies a given 
condition. You supply a test-function pointer / that returns true for a certain 
condition. You can pass arbitrary arguments via args. Returns if no object 
in the array meets the condition. 

See also: LastThat 
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Flush void Flush ( TShouldDelete::DeleteType = TShouldDelete: :Def Delete ) 

Flushes the dequeue without destroying it. The fate of any objects removed 
depends on the current ownership status and the value of the dt argument. 

See also: TShouldDeletenownsElements 

ForEach vo id ForEach(IterFunc, void *args ); 

Executes function / for each dequeue element. ForEach creates an internal 
iterator to execute the given function for each element in the array. The args 
argument lets you pass arbitrary data to this function. 

GetltemslnContainer i nt GetltemsInContainerO const 

Returns the number of items in the dequeue. 



GetLeft 



GetRight 



IsEmpty 



IsFull 



LastThat 



PeekLeft 



T GetLeft (); 

Returns the object at the left end and removes it from the dequeue. The 
debuggable version throws an exception when the dequeue is empty. 

• See also: PeekLeft 

T GetRight ( ) ; 

Same as GetLeft, except that the right end of the dequeue is returned. 

See also: PeekRight 

int IsEmpty () const 

Returns 1 if the dequeue has no elements; otherwise returns 0. 

int IsFull () const • 

Returns 1 if the dequeue is full; otherwise returns 0. 

T *LastThat(CondFunc, void *args ) const; 

Returns a pointer to the last object in the dequeue that satisfies a given 
condition. You supply a test function pointer, /, that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. Note that LastThat creates its own 
internal iterator, so you can treat it as a "search" function. 

See also: FirstThat, ForEach 

Const T& PeekLeft () const 

Returns the object at the left end (head) of the dequeue. The object stays in 
the dequeue. 

See also: GetLeft 
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PeekRight 



PutLeft 



PutRight 



Data 



Left 



Right 



Next 



Prev 



Const T& PeekRight ()■ const 

Returns the object at the right end (tail) of the dequeue. The object stays in 
the dequeue. 

See also: GetRight 

void PutLeft ( const T& ) ; 

Adds (pushes) the given object at the left end (head) of the dequeue. 

void PutRight ( const T& ) ; 

Adds (pushes) the given object at the right end (tail) of the dequeue. 

Protected data members 

Vect Data; 

The vector containing the dequeue's data. 

unsigned Left; 

Index to the leftmost element of the dequeue. 

unsigned Right; 

Index to the rightmost element of the dequeue. 

Protected member functions 

unsigned Next( unsigned index ) const 

Returns index + 1. Wraps around to the head of the dequeue. 

See also: Prev 

unsigned Prev( unsigned index ) const 

Returns index - 1. Wraps around to the tail of the dequeue. 



TMDequeAsVectorlterator template 



deques.h 



Implements an iterator object for a managed, vector-based dequeue. 
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Public constructors 



Constructor 



TMDequeAsVectorIterator( const TMDequeAsVector<T,Alloc> &d ) 
Constructs an object that iterates on TMDequeAsVector objects. 



Public member functions 



Current 



Restart 



Const T& Current ( ) ; 
Returns the current object. 
void Restart () ; 
Restarts iteration. 



Operators 



operator ++ const T& operator ++ ( int ); 

Moves to the next object, and returns the object that was current before the 
move (post-increment). 

Const T& operator ++ (); 

Moves to the next object, and returns the object that was current after the 
move (pre-increment). 

operator int operator int () ; 

Converts the iterator to an integer value for testing if objects remain in the 
iterator. Iterator converts to if nothing remains in the iterator. 



TDequeAsVector template 



deques.h 



Implements a dequeue of T objects, using a vector as the underlying 
implementation. TStandardAllocator is used to manage memory. See 
TMDequeAsVector on page 383 for members. 



Public constructors 



Constructor TDequeAsVector ( unsigned max = DEFAULT_DEQUE_SIZE 

Constructs a dequeue of max size. 
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TDequeAsVectorlterator template 



deques.h 



Implements an iterator object for a vector-based dequeue. See 
TMDequeAsVectorlterator on page 385 for members. 

Public constructors 



Constructor 



TDequeAsVectorlterator! const TDequeAsVector<T> &d ) 
Constructs an object that iterates on TMDequeAsVector objects. 



TMIDequeAsVector template 



deques.h 



Implements a managed, indirect dequeue of pointers to objects of type T, 
using a vector as the underlying implementation. 



CondFunc 



IterFunc 



Type definitions 



typedef int ( *CondFunc) (const T &, void *); 

Function type used as a parameter to FirstThat and LastThat member 
functions. 

typedef void ( *IterFunc) (T &, void *); 

Function type used as a parameter to ForEach member function. 



Public constructors 



Constructor 



TMIDequeAsVector ( unsigned sz .= DEFAULT_DEQUE_SIZE ) 
Constructs an indirect dequeue of max size. 



Public member functions 



FirstThat 



T *FirstThat (CondFunc, void *args ) const; 

Returns a pointer to the first object in the dequeue that satisfies a given 
condition. You supply a test-function pointer / that returns true for a certain 
condition. You can pass arbitrary arguments via args. Returns if no object 
in the array meets the condition. 
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Flush 



ForEach 



See also: LastThat 

void Flush ( TShouldDelete::DeleteType = TShouldDelete: :Def Delete ); 

Flushes the dequeue without destroying it. The fate of any objects removed 
depends on the current ownership status and the value of the dt argument. 



void ForEach (IterFunc, void *args ); 

Executes function /for each dequeue element. ForEach creates an internal 
iterator to execute the given function for each element in the array. The args 
argument lets you pass arbitrary data to this function. 

GetltemslnContainer i nt GetltemsInContainerO const 



GetLeft 



GetRight 



IsEmpty 



IsFull 



LastThat 



PeekLeft 



Returns the number of items in the dequeue. 

T *GetLeft() 

Returns a pointer to the object at the left end and removes it from the 
dequeue. Returns if the dequeue is empty. 

See also: PeekLeft 

T *GetRight() 

Same as GetLeft, except that the right end of the dequeue is returned. 

See also: PeekRight 

int IsEmpty () const 

Returns 1 if a dequeue has no elements; otherwise returns 0. 

int isFull() const 

Returns 1 if a dequeue is full; otherwise returns 0. 

T *LastThat (CondFunc, void *args ) const; 

Returns a pointer to the last object in the dequeue that satisfies a given 
condition. You supply a test function pointer, /, that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. Note that LastThat creates its own 
internal iterator, so you can treat it as a "search" function. 

See also: FirstThat, ForEach 

T *PeekLeft() const 

Returns a pointer to the object at the left end (head) of the dequeue. The 
object stays in the dequeue. 

See also: GetLeft 
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PeekRight T *PeekRight() const 

Returns the object at the right end (tail) of the dequeue. The object stays in 
the dequeue. 

See also: GetRight 

PutLeft void PutLeftl T *t ) 

Adds (pushes) the given object pointer at the left end (head) of the 
dequeue. 

PutRight vo id PutRighM T *t ) 

Adds (pushes) the given object pointer at the right end (tail) of the 
dequeue. 

TMIDequeAsVectorlterator template deques.h 

Implements an iterator for the family of managed, indirect dequeues 
implemented as vectors. See TMDequeAsVectorlterator on page 385 for 
members. 



Public constructors 



Constructor 



TMIDequeAsVectorlterator ( const TMIDequeAsVector<T,Alloc> &d 
Creates an object that iterates on TMIDequeAsVector objects. 



TIDequeAsVector template deques.h 

Implements an indirect dequeue of pointers to objects of type T, using a 
vector as the underlying implementation. See TMIDequeAsVector on page 
387 for members. 

Public constructors 

Constructor TIDequeAsVector ( unsigned sz = DEFAULT_DEQUE_SIZE ) : 

TMIDequeAsVector<T,TStandardAllocator>(sz) 

Constructs an indirect dequeue of max size. 
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TIDequeAsVectorlterator template 



deques.h 



Implements an iterator for the family of indirect dequeues implemented as 
vectors. See TMDequeAsVectorlterator 385 for members. 

Public constructors 



Constructor 



TIDequeAsVectorlterator ( const TIDequeAsVector<T> &d ) 
Constructs an object that iterates on TIDequeAsVector objects. 



TMDequeAsDoubleList template 



deques.h 



Implements a managed dequeue of objects of type T, using a double-linked 
list as the underlying implementation. 



CondFunc 



IterFunc 



Type definitions 



typedef int ( *CondFunc) (const T &, void *); 

Function type used as a parameter to FirstThat and LastThat member 
functions. 

typedef void ( *IterFunc) (T &, void *); 

Function type used as a parameter to ForEach member function. 



Public member functions 



FirstThat 



Flush 



ForEach 



T *FirstThat (CondFunc, void *args ) const 

Returns a pointer to the first object in the dequeue that satisfies a given 
condition. You supply a test-function pointer /that returns true for a certain 
condition. You can pass arbitrary arguments via args. Returns if no object 
in the array meets the condition. 

See also: LastThat 

void Flush ( int. del ) 

Flushes the dequeue without destroying it. The fate of any objects removed 
depends on the current ownership status and the value of the dt argument. 

void ForEach (IterFunc, void *args ) 
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Executes function / for each dequeue element. ForEach creates an internal 
iterator to execute the given function for each element in the array. The args 
argument lets you pass arbitrary data to this function. 

GetltemslnContainer i nt GetltemsInContainerO const 



GetLeft 



GetRight 



IsEmpty 



IsFull 



LastThat 



PeekLeft 



PeekRight 



PutLeft 



PutRight 



Returns the number of items in the dequeue. 

T GetLeft () 

Returns the object at the left end and removes it from the dequeue. 

T GetRight () 

Same as GetLeft, except that the right end of the dequeue is returned. 

See also: PeekRight 

int IsEmpty () const 

Returns 1 if a dequeue has no elements; otherwise returns 0. 

int IsFull () const 

Returns 1 if a dequeue is full; otherwise returns 0. 

T *LastThat(CondFunc, void *args ) const 

Returns a pointer to the last object in the dequeue that satisfies a given 
condition. You supply a test function pointer, /, that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. Note that LastThat creates its own 
internal iterator, so you can treat it as a "search" function. 

See also: FirstThat, ForEach 

Const T& PeekLeft () const 

Returns a reference to ( the object at the left end (head) of the dequeue. The 
object stays in the dequeue. 

See also: GetLeft 

Const T& PeekRight () const 

Returns a reference to the object at the right end (tail) of the dequeue. The 
object stays in the dequeue. 

See also: GetRight 

void PutLeft ( const T& t ) 

Adds (pushes) the given object at the left end (head) of the dequeue. 

void PutRight ( const T& t ) 
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Adds (pushes) the given object at the right end (tail) of the dequeue. 

TMDequeAsDoubleListlterator template deques.h 

Implements an iterator object for a double-list based deques. See 
TMDoubleListlteratorlmp on page 404 for members. 

Public constructors 

Constructor TMDequeAsDoubleListlterator ( const TMDequeAsDoubleList<T, Alloo & s ) 

Constructs an object that iterates on TMDequeAsDoubleList objects. 

TDequeAsDoubleList template deques.h 

Implements a dequeue of objects of type T, using a double-linked list as the 
underlying implementation, and T Standard Allocator as its memory manager. 
See TMDequeAsDoubleList on page 390 for members. 

TDequeAsDoubleListlterator template deques.h 

Implements an iterator object for a double-list based dequeue. 

Public constructors 

Constructor . TMDequeAsDoubleListlterator ( const TMDequeAsDoubleList<T, Alloo & s ) 

Constructs an object that iterates on TDequeAsDoubleList objects. 

TMIDequeAsDoubleList template deques.h 

Implements a managed dequeue of pointers to objects of type T, using a 
double-linked list as the underlying implementation. 



Type definitions 



CondFunc 



typedef int ( *CondFunc) (const T &, void *); 
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IterFunc 



Function type used as a parameter to FirstThat and LastThat member 
functions. 

typedef void ( *IterFunc) (T &, void *); 

Function type used as a parameter to ForEach member function. 



Public member functions 



FirstThat 



Flush 



ForEach 



T *FirstThat(CondFunc, void *args ) const 

Returns a pointer to the first object in the dequeue that satisfies a given 
condition. You supply a test-function pointer / that returns true for a certain 
condition. You can pass arbitrary arguments via args. Returns if no object 
in the array meets the condition. 



See also: LastThat 

void Flush ( TShouldDelete: :DeleteType dt 



TShouldDelete: :Def Delete 



Flushes the dequeue without destroying it. The fate of any objects removed 
depends on the current ownership status and the value of the dt argument. 

void ForEach (IterFunc, void *args ) 



Executes function /for each dequeue element. ForEach creates an internal 
iterator to execute the given function for each element in the array. The args 
argument lets you pass arbitrary data to this function. 

GetltemslnContainer i nt GetltemsInContainerl 



GetLeft 



GetRight 



IsEmpty 



IsFull 



const 
Returns the number of items in the dequeue. 

T *GetLeft() 

Returns a pointer to the object at the left end and removes it from the 
dequeue. Returns if the dequeue is empty. 

See also: PeekLeft 

T *GetRight() 

Same as GetLeft, except that a pointer to the object at the right end of the 
dequeue is returned. 

See also: PeekRight 

int IsEmpty () const 

Returns 1 if the dequeue has no elements; otherwise returns 0. 

int IsFull () const 
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LastThat 



PeekLeft 



PeekRight 



PutLeft 



PutRight 



Returns 1 if the dequeue is full; otherwise returns 0. 

T *LastThat(CondFunc, void *args ) const 

Returns a pointer to the last object in the dequeue that satisfies a given 
condition. You supply a test function pointer, /, that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. Note that LastThat creates its own 
internal iterator, so you can treat it as a "search" function. 

See also: FirstThat, ForEach 

T *PeekLeft() const 

Returns a pointer to the object at the left end (head) of the dequeue. The 
object stays in the dequeue. 

T *PeekRight() const 

Returns the object at the right end (tail) of the dequeue. The object stays in 
the dequeue. 

void PutLeft ( T *t ) 

Adds (pushes) the given object pointer at the left end (head) of the 
dequeue. 

void PutRight ( T *t ) 

Adds (pushes) the given object pointer at the right end (tail) of the 
dequeue. 



TMIDequeAsDoubleListlterator template 



deques.h 



Implements an iterator for the family of managed, indirect dequeues 
implemented as double lists. See TMDoubleListlteratorlmp on page 404 for 
members. 

Public constructors 



Constructor 



TMIDequeAsDoubleListlterator ( const TMIDequeAsDoubleList<T,Alloc> s 
Constructs an object that iterates on TMIDequeAsDoubleList objects. 
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TIDequeAsDoubleList template 



Dequeue containers 



deques.h 



Implements a dequeue of pointers to objects of type T, using a double- 
linked list as the underlying implementation. See TMIDequeAsDoubleList on 
page 392 for members. 



TIDequeAsDoubleListlterator template 



deques.h 



Implements an iterator for the family of indirect dequeues implemented as 
double lists. See TMDoubleListlteratorlmp on page 404 for members. 



Constructor 



Public constructors 



TIDequeAsDoubleListlterator! const TIDequeAsDoubleList<T> & s ) 
Constructs an object that iterates on TIDequeAsDoubleList objects. 



TMDictionaryAsHashTable template 



dict.h 



Implements a managed dictionary using a hash table as the underlying 
FDS, and using the user-supplied storage allocator A. It assumes that T is 
one of the four types of associations, and that T has meaningful copy and 
== semantics as well as a default constructor. 



HashTable 



Protected data members 



TMHashTableImp<T,A> HashTable; 
Implements the underlying hash table. 



Constructor 



Public constructors 



TMDictionaryAsHashTable ( unsigned size = DEFAULT_HASH_TABLE_SIZE 
Constructs a dictionary with the specified size. 



Add 



Public member functions 



int Add( const T& t 
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Adds item t if not already in the dictionary. 

int Detach ( const T& t, int del = ) 

Removes item t from the dictionary, and deletes if del is 1. If del is the item 
is not deleted. 

T * Find( constT& t ) 

Returns a pointer to item t . 

void Flush ( int del = ) 

Removes all items from the dictionary. The items are deleted if del is 1. If del 
is the items are not deleted. 

void ForEach( void ( *func) (T &, void *), void * args ) 

Creates an internal iterator that executes the given function / for each item 
in the container. The args argument lets you pass arbitrary data to this 
function. 

GetltemslnContainer inline unsigned GetltemsInContainerO 

Returns the number of items in the dictionary. 
IsEmpty inline int IsEmptyO 

Returns 1 if the dictionary is empty; otherwise returns 0. 



Detach 



Find 



Flush 



ForEach 



TMDictionaryAsHashTablelterator template 



dict.h 



Implements an iterator that traverses TMDictionaryAsHashTable objects, 
using the user-supplied storage allocator A. 

Public constructors 



Constructor 



TMDictionaryAsHashTableIterator(TMDictionaryAsHashTable<T,A> & t ) 

Constructs an iterator object that traverses a TMDictionaryAsHashTable 
container. 



Public member functions 



Current 



Const T& Current () 
Returns the current object. 
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Restart 



void Restart ( ) ; 

Restarts iteration from the beginning of the dictionary. 



Operators 



operator int operator int ( ) 

Converts the iterator to an integer value for testing if objects remain in the 
iterator. The iterator converts to if nothing remains in the iterator. 

operator ++ Const T& operator ++ (int) 

Moves to the next object, and returns the object that was current before the 
move (post-increment). 

Const T& operator ++ () 

Moves to the next object, and returns the object that was current after the 
move (pre-increment). 



TDictionaryAsHashTable template 



dict.h 



Implements a dictionary objects of type T, using the system storage 
allocator T Standard Allocator. It assumes that T is one of the four types of 
associations, and that T has meaningful copy and == semantics as well as a 
default constructor. See TMDictionaryAsHashTable on page 395 for 
members. 

Public constructors 

Constructor TDictionaryAsHashTable ( unsigned size = DEFAULT_HASH_TABLE_SIZE ) 

Constructs a dictionary with the specified size. 



TDictionaryAsHashTablelterator template 



dict.h 



Implements an iterator that traverses TDictionaryAsHashTable objects, using 
the system storage allocator T Standard Allocator. 
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Public constructors 



Constructor 



TDictionaryAsHashTableIterator( TDictionaryAsHashTable<T> & t ) ■ 

Constructs an iterator object that traverses a TDictionaryAsHashTable 
container. 



TMIDictionaryAsHashTable template 



dict.h 



Implements a managed indirect dictionary using a hash table as the 
underlying FDS, and using the user-supplied storage allocator A. It 
assumes that T is of class TAssociation. 



Public constructors 



Constructor 



TMIDictionaryAsHashTable ( unsigned size: = DEFAULT_HASH_TABLE_SIZE 
Constructs an indirect dictionary with the specified size. 



Public member functions 



Add 



Detach 



Find 



Flush 



ForEach 



int Add( T * t ) \ 

Adds a pointer to item t if not already in the dictionary. 

int Detach ( T * t, int del = . ) 

Removes the pointer to item t from the dictionary, and deletes if del is 1. If 
del is the item is not deleted. 

T * Find( T * t) 

Returns a pointer to item t: 

void Flush ( int del = ) 

Removes all items from the dictionary. The item is deleted if del is 1. If del is 
the item is not deleted. 

void ForEach( void ( *func) (T &, void *), void * args ); 

Creates an internal iterator that executes the given function / for each item 
in the container. The args argument lets you pass arbitrary data to this 
function. 



GetltemslnContainer inline unsigned GetltemsInContainerl 
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IsEmpty 



Returns the number of items in the dictionary. 

inline int IsEmpty () 

Returns 1 if the dictionary is empty; otherwise returns 0. 



TMIDictionaryAsHashTablelterator template 



dict.h 



Implements an iterator that traverses TMIDictionaryAsHashTable objects, 
using the user-supplied storage allocator A. 

Public constructors 



Constructor 



TMIDictionaryAsHashTablelteratorf TMIDictionaryAsHashTable<T ; A> & t ) 

Constructs an iterator object that traverses a TMIDictionaryAsHashTable 
container. 



Public member functions 



Current 



Restart 



T *Current() 

Returns a pointer to the current object. 

void Restart ( ) ; 

Restarts iteration from the beginning of the dictionary. 



Operators 



operator int operator into 

Converts the iterator to an integer value for testing if objects remain in the 
iterator. The iterator converts to if nothing remains in the iterator. 

operator 4+ T Operator ++ (int) 

Moves to the next object, and returns a pointer to the object that was 
current before the move (post-increment). 

T, *operator ++ 

Moves to the next object, and returns a pointer to the object that was 
current after the move (pre-increment). 
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TIDictionaryAsHashTable template dict.h 

Implements an indirect dictionary using a hash table as the underlying 
FDS, and using the system storage allocator T Standard Allocator. It assumes 
that T is one of the four types of associations. See 
TMIDictionaryAsHashTable on page 398 for members. 

Public constructors 

Constructor TIDictionaryAsHashTable ( unsigned size = DEFAULT_HASH_TABLE_SIZE ) 

Constructs an indirect dictionary with the specified size. 

TIDictionaryAsHashTablelterator template dict.h 

Implements an iterator that traverses TIDictionaryAsHashTable objects, 
using the user-supplied storage allocator A. See 
TMTDictionary AsHashT ablelterator on page 399 for members. 

Public constructors 

Constructor TIDictionaryAsHashTableIterator( TIDictionaryAsHashTable<T> & t ) 

Constructs an iterator object that traverses a TIDictionaryAsHashTable 
container. 

TDictionary template dict.h 

A simplified name for TDictionary AsHashTable. See TDictionary AsHashT able 
on page 397 for members. 

TDictionarylterator template dict.h 

A simplified name for TDictionary AsHashT ablelterator. See 
TDictionary AsHash Tablelterator on page 397 for members. 
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Public constructors 



Constructor 



TDictionaryIterator( const TDictionary<T> & a ) 

Constructs an iterator object that traverses a TDictionary container. 



TMDoubleListElement template 



dlistimp.h 



This class defines the nodes for double-list classes TMDoubleListlmp and 
TMIDoubleListlmp. 



data 



Next 



Prev 



Constructor 



Constructor 



Public data members 



T data; 

Data object contained in the double list. 

TMDoubleListElement<T> *Next; 

A pointer to the next element in the double list. 

TMDoubleLi st Element <T> *Prev; 

A pointer to the previous element in the double list. 



Public constructors 



TMDoubleListElement ( ) ; 

Constructs a double-list element. 

TMDoubleListElement ( T& t, TMDoubleListElement<T> *p ) 

Constructs a double-list element, and inserts after the object pointed to by 



Operators 



operator delete void operator delete ( void * ); 

Deletes an object. 

operator new vo id *operator new( size_t sz ) ; 

Allocates a memory block of sz amount, and returns a pointer to the 
memory block. 



Chapter 7, The C++ container classes 



401 



Double list containers 



TMDoubleListlmp template 



dlistimp.h 



Implements a managed, double-linked list of objects of type T. Assumes 
that T has meaningful copy semantics, operator ==, and a default 
constructor. 



CondFunc 



IterFunc 



Type definitions 



typedef int ( *CondFunc) (const T &, void *); 

Function type used as a parameter to FirstThat and LastThat member 
functions. 

typedef void ( *IterFunc) (T &, void *); 

Function type used as a parameter to ForEach member function. 



Public constructors 



Constructor TMDoubleListlmp () 

Constructs an empty, managed, double-linked list. 

Public member functions 



Add 



AddAtHead 



AddAtTail 



Detach 



FirstThat 



int Add( const T& t )'; 

Add the given object at the beginning of the list. 

int AddAtHead ( const T& t ) ; 

Add the given object at the beginning of the list. 

int AddAtTail ( const T& ) ; 

Adds the given object at the end (tail) the list. 

int Detach ( const T&, int = ); 

Removes the first occurrence of the given object encountered by searching 
from the beginning of the list. For direct containers the second argument is 
ignored. For indirect containers the int argument determines if the 
detached object is itself destroyed. See TShouldDelete on page 460 for 
details. 

T *FirstThat( int ( *) (const T &, void *), void * ). const; 
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Flush 



ForEach 



IsEmpty 
LastThat 



PeekHead 



PeekTail 



Returns a pointer to the first object in the double-list that satisfies a given 
condition. You supply a test-function pointer /that returns true for a certain 
condition. You can pass arbitrary arguments via args. Returns if no object 
in the array meets the condition. 

void Flush ( int = ); 

Removes all elements from the list without destroying the list. The value of 
dt determines whether the elements themselves are destroyed. By default, 
the ownership status of the array determines their fate, as explained in the 
Detach member function. You can also set dt to Delete and NoDelete. 

void ForEach (IterFunc, void * ); . 

ForEach creates an internal iterator to execute the given function for each 
element in the array. The args argument lets you pass arbitrary data to this 
function. 

int IsEmpty () const 

Returns 1 if array contains no elements; otherwise returns 0. 

T *LastThat( int ( *) (const T &, void *), void * ) const; 

Returns a pointer to the last object in the double list that satisfies a given 
condition. You supply a test function pointer, /, that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. Note that LastThat creates its own 
internal iterator, so you can treat it as a "search" function. 

See also: FirstThat, ForEach 

Const T& PeekHead () const 

Returns a reference to the Head item in the double list, without removing it. 

Const T& PeekTail () const 

Returns a reference to the Tail item in the double list, without removing it. . 



Protected data members 



Headjail 



TMDoubleListElement<T> Head, . Tail; 

The head and tail items of the double list. 



Protected member functions 



FindDetach 



virtual TMDoubleListElement<T> *FindDetach( const T& t 
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FindPred 



Determines whether an object is in the list, and returns a pointer to its 
predecessor. Returns if not found. 

virtual TMDoubleListElement<T> *FindPred( const T& ) ; 

Finds the element that would be followed by the parameter. The function 
does not check whether the parameter is actually there. This can be used for 
inserting (insert after returned element pointer). 



TMDoubleListlteratorlmp template 



dlistimp.h 



Implements a double list iterator. This iterator works with any direct 
double-linked list. For indirect lists, see TMIDoubleListlteratorlmp on 
page 409. 

Public constructors 



Constructor 



TMDoubleListlteratorlmp ( const TDoubleListImp<T> &1 ) 
Constructs an iterator that traverses TDoubleListlmp objects. 



Public member functions 



Current 



Restart 



Const T& Current () 

Returns the current object. 

void Restart () 

Restarts iteration from the beginning of the list. 



Operators 



operator int ' operator into 

Converts the iterator to an integer value for testing if objects remain in the 
iterator. The iterator converts to if nothing remains in the iterator. 

operator ++ con st T& operator ++ ( int ) 

Moves to the next object, and returns the object that was current before the 
move (post-increment). 

const T& operator ++ () 
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Moves to the next object, and returns the object that was current after the 
move (pre-increment). 

operator-- cons t t& operator — ( int ) 

Moves to the previous object, and returns the object that was current before 
the move (post-decrement). 

const T& operator -- () 

Moves to the previous object, and returns the object that was current after 
the move (pre-decrement). 

TDoubleListlmp template dlistimp.h 

Implements a double-linked list of objects of type T, using 
T Standard Allocator for memory management. Assumes that T has 
meaningful copy semantics and a default constructor. See TMDoubleListlmp 
on page 402 for members. 

Public constructors 

Constructor TDoubleListlmp () 

Constructs an empty double-linked list. 

TDoubleListlteratorlmp template dlistimp.h 

Implements a double list iterator. This iterator works with anydirect 
double-linked list. See TMDoubleListlteratorlmp on page 404 for members. 



Public constructors 



Constructor 



TDoubleListlteratorlmp ( const TDoubleListImp<T> &1 ) 
Constructs an iterator that traverses TDoubleListlmp objects. 



Chapter 7, The C++ container classes 405 



Double list containers 



TMSDoubleListlmp template 



dlistimp.h 



FindDetach 



FindPred 



Implements a managed, sorted, double-linked list of objects of type T. It 
assumes that T has meaningful copy semantics, a == operator, a < operator, 
and a default constructor. See TMDoubleListlmp on page 402 for members. 

Protected member functions 

In addition to the following member functions, TMSDoubleListlmp inherits 
member functions from TMDoubleListlmp (see page 402). 

virtual ■TMDoubleListElement<T> *FindDetach( const T& ) ; ■ 

Determines whether an object is in the list, and returns a pointer to its 
predecessor. Returns if not found. 

virtual TMDoubleListElement<T> *FindPred( const T& ); 

Finds the element that would be followed by the parameter. The function 
does not check whether the parameter is actually there. This can be used for 
inserting (insert after returned element pointer). 



TMSDoubleListlteratorlmp template 



dlistimp.h 



Implements a double list iterator. This iterator works with any direct 
double-linked list. See TMDoubleListlteratorlmp on page 404 for members. 

Public constructors 



Constructor 



TMSDoubleListlteratorlmp ( const TMSDoubleListImp<T,Alloc> &1 ) 
Constructs an iterator that traverses TMSDoubleListlmp objects. 



TSDoubleListlmp template 



dlistimp.h 



Implements a sorted, double-linked list of objects of type T. It assumes that 
T has meaningful copy semantics, a meaningful < operator, and a default 
constructor. See TMSDoubleListlmp on page 406 for members. 
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TSDoubleListlteratorlmp template 



Double list containers 



dlistimp.h 



Implements a double list iterator. This iterator works with any direct 
double-linked list. See TMDoubleListlteratorlmp on page 404 for members. 



Constructor 



Public constructors 



TSDoubleListlteratorlmp ( const TSDoubleListImp<T> &1 ) 
Constructs an iterator that traverses TSDoubleListlmp objects. 



TMIDoubleListlmp template 



dlistimp.h 



Implements a managed, double-linked list of pointers to objects of type 
T.The contained objects need a valid == operator. Since pointers always 
have meaningful copy semantics, this class can handle any type of object. 



CondFunc 



IterFunc 



Type definitions 



typedef int ( *CondFunc) (const T &, void *).; 

Function type used as a parameter to FirstThat and LastThat member 
functions. 

typedef void ( *IterFunc) (T &, void *); 

Function type used as a parameter to ForEach member function. 



Public member functions 



Add 



AddAtHead 



AddAtTail 



Detach 



int Add( T *t ) 

Adds an object pointer to the double list. 

int AddAtHead ( T *t ) ; 

Add the given object at the beginning of the list. 

int AddAtTail ( T *t ) 

Adds an object pointer to the tail of the double list. 

int Detach ( T *t, int del = ) 
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DetachAtHead 



DetachAtTail 



FirstThat 



Flush 



ForEach 



Removes the given object pointer from the list. The second argument 
specifies whether the object should be deleted. See TShouldDelete on 
page 460. 

int DetachAtHead ( int del = ) 

Deletes the object pointer from the head of the list. 

int DetachAtTail ( int del ■= ) 

Deletes the object pointer from the tail of the list. 

T *FirstThat( int ( *) (const T &, void *), void * ) const; 

Returns a pointer to the first object in the double list that satisfies a given 
condition. You supply a test-function pointer / that returns true for a certain 
condition. You can pass arbitrary arguments via args. Returns if no object 
in the array meets the condition. 

See also: LastThat 

void Flush ( int = ) ; 

Removes all elements from the list without destroying the list. The value of 
dt determines whether the elements themselves are destroyed. By default, 
the ownership status of the array determines their fate, as explained in the 
Detach member function. You can also set dt to Delete and NoDelete. 



void ForEach (IterFunc, void * ); 

Executes function / for each double-list element. ForEach creates an internal 
iterator to execute the given function for each element in the array. The args 
argument lets you pass arbitrary data to this function. 

GetltemslnContainer unsigned GetltemsInContainerO const. 

Returns the number of items in the array. 

int IsEmptyO const 

Returns 1 if array contains no elements; otherwise returns 0. 

T *LastThat( int ( *) (const T &, void *), void * ) const; 

Returns a pointer to the last object in the list that satisfies a given condition. 
You supply a test function pointer, /, that returns true for a certain 
condition. You can pass arbitrary arguments via args. Returns if no object 
in the array meets the condition. Note that LastThat creates its own internal 
iterator, so you can treat it as a "search" function. - 



IsEmpty 



LastThat 



PeekHead 



See also: FirstThat, ForEach 

T *PeekHead() const 
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PeekTail 



Returns the object pointer at the Head of the list, without removing it. 

T *PeekTail() const 

Returns the object pointer at the Tail of the list, without removing it. 



FindPred 



Protected member functions 



virtual TDoubleListElement<void *> *FindPred( void * ); 

Finds the element that would be followed by the parameter. The function 
does not check whether the parameter is actually there. This can be used for 
inserting (insert after returned element pointer). 



TMIDoubleListlteratorlmp template 



dlistimp.h 



Implements a double list iterator. This iterator works with any indirect 
double list. For direct lists, see TMDoubleListlteratorlmp on page 404. 



Constructor 



Public constructors 



TMIDoubleListlteratorlmp ( const TMIDoubleListImp<T,Alloc> &1 ) 
Constructs an object that iterates on TIDoubleListlmp objects. 



Current 



Restart 



Public member functions 



T *Current() 

Returns the current object pointer. 

void Restart () 

Restarts iteration from the beginning of the list. 



operator ++ 



Operators 



T *operator ++ (int) 

Moves to the next object, and returns the object that was current before the 
move (post-increment). 



Chapter 7, The C++ container classes 



409 



Double list containers 



T *operator ++ () 

Moves to the next object, and returns the object that was current after the 
move (pre-increment). 

TIDoubleListlmp template dlistimp.h 

Implements a double-linked list of pointers to objects of type T, using 
T Standard Allocator for memory management. Since pointers always have 
meaningful copy semantics, this class can handle any type of object. See 
TMIDoubleListlmp on page 407 for members. 

TIDoubleListlteratorlmp template dlistimp.h 

Implements a double list iterator. This iterator works with any indirect 
double list. See TMIDoubleListlteratorlmp on page 409 for members. 

Public constructors 

Constructor TIDoubleListlteratorlmp ( const TIDoubleListImp<T> &1 ) 

Constructs an object that iterates on TIDoubleListlmp objects. 

TMISDoubleListlmp template dlistimp.h 

Implements a managed, sorted, double-linked list of pointers to objects of 
type T. Since pointers always have meaningful copy semantics, this class 
can handle any type of object. 

Protected member functions 

In addition to the member function described here, TMISDoubleListlmp 
inherits member functions (see TMIDoubleListlmp on page 407). 

FindDetach virtual TMDoubleListElement<void *> *FindDetach( void * ); 

Determines whether an object is in the list, and returns a pointer to its 
predecessor. 
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TMISDoubleListlteratorlmp template dlistimp.h 

Implements a double list iterator. This iterator works with any indirect, 
sorted double list. See TMIDoubleListlteratorlmp on page 409 for members. 

Public constructors 

Constructor TMISDoubleListlteratorlmp ( const TMISDoubleListImp<T,Alloc> &1 ) 

Constructs an object that iterates on TMISDoubleListlmp objects. 

TISDoubleListlmp template dlistimp.h 

Implements a sorted, double-linked list of pointers to objects of type T, 
using T Standard Allocator for memory management. Since pointers always 
have meaningful copy semantics, this class can handle any type of object. 
See TMIDoubleListlmp on page 407 for members. 

TISDoubleListlteratorlmp template dlistimp.h 

Implements a double list iterator. This iterator works with any indirect, 
sorted double list. See TMIDoubleListlteratorlmp on page 409 for members. 

Public constructors 

Constructor TISDoubleListlteratorlmp ( const TISDoubleListImp<T> &1 ) 

Constructs an object that iterates on TMISDoubleListlmp objects. 

TMHashTablelmp template hashimp.h 

Implements a managed hash table of objects of type T, using the user- 
supplied storage allocator A. It assumes that T has meaningful copy and == 
semantics, as well as a default constructor. 

Public constructors and destructor 

Constructor ' TMHashTablelmp ( unsigned aPrime = DEFAULT_HASH_TABLE_SIZE ) 
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Destructor 



Constructs a hash table. 

-TMHashTablelmpO 

Calls member function Flush to delete the container. 



Public member functions 



Add 



Detach 



Find 



int Add( const T& t ) ; 
Adds item t to the hash table. 

int Detach ( const T& t, int del=0 ); 

Removes item t from the hash table. If del is set to 0, t is deleted; if del is set 
to 1, t is not deleted. 



T * Find( const T& t ) const 
Returns a pointer to item t. 
Flush V0 i d F i ush ( int del = ) 

Flushes all items in the hash table. The hash table is destroyed if del is 
nonzero. 

ForEach vo id ForEach(void ( *f ) (T &, void *), void *args) ; 

Creates an internal iterator that executes the given function /for each item 
in the container. The args argument lets you pass arbitrary data to this 
function. 

GetltemslnContainer unsigned GetltemsInContainerO const 

Returns the number of items in the hash table. 
IsEmpty i nt isEmptyO const 

Returns 1 if the hash table is empty; otherwise returns 0. 



TMHashTablelteratorlmp template 



hashimp.h 



Implements an iterator for traversing TMHashTablelmp containers, using 
the user-supplied storage allocator Alloc. 



Public constructors and destructor 



Constructor 



TMHashTablelteratorlmp ( const TMHashTableImp<T,A> & h 
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Destructor 



Constructs an iterator object that traverses a TMHashTablelmp container. 

-TMHashTablelteratorlmp ( ) 
Destroys the iterator. 



Public member functions 



Current 



Restart 



Const T& Current () 

Returns the current object. 

void Restart ( ) ; 

Restarts iteration from the beginning of the hash table. 



Operators 



operator int operator into 

Converts the iterator to an integer value for testing if objects remain in the 
iterator. The iterator converts to if nothing remains in the iterator. 

operator ++ const T& operator ++ (int) 

Moves to the next object, and returns the object that was current before the 
move (post-increment). 

Const T& operator ++ () 

Moves to the next object, and returns the object that was current after the 
move (pre-increment). 



THashTablelmp template 



hashimp.h 



Implements a hash table of objects of type T, using the system storage 
allocator T Standard Allocator. It assumes that T has meaningful copy and == 
semantics as well as a default constructor. See TMHashTablelmp on page 411 
for members. 

Public constructors 



Constructor 



THashTablelmp ( unsigned aPrime = DEFAULT_HASH_TABLE_SIZE ) 

Constructs a hash table that uses T Standard Allocator for memory 
management. 
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THashTablelteratorlmp template 



hashimp.h 



Implements an iterator for traversing THashTablelmp containers. See 
TMHashTablelteratorlmp on page 412 for members. 



Constructor 



Public constructors 



THashTablelteratorlmp ( const THashTableImp<T,A> & h ) 

Constructs an iterator object that traverses a THashTablelmp container. 



TMIHashTablelmp template 



hashimp.h 



Implements a managed hash table of pointers to objects of type T, using the 
user-supplied storage allocator Alloc. 



Constructor 



Public constructors 



TMIHashTablelmp ( unsigned aPrime = DEFAULT_HASH_TABLE_SIZE 
Constructs an indirect hash table. 



Public member functions 



Add 



Detach 



Find 



Flush 



ForEach 



int Add( T * t ) 

Adds a pointer to item t to the hash table. 

int Detach ( T * t, int del = ) 

Removes a pointer to item t from the hash table, t is deleted if del is set 1, 
and not deleted if del is set to 0. 

T * Find( const T * t ) const 

Returns a pointer to item t . 

void Flush ( int del = ) 

Flushes all items in the hash table. The hash table is destroyed if del is 
nonzero. 

void ForEach(void ( *f ) (T &, void *) ; -void *args) ; 
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Creates an internal iterator that executes the given function /for each item 
in the container. The args argument lets you pass arbitrary data to this 
function. 

GetltemslnContainer unsigned GetltemsInContainerO const 

Returns the number of items in the hash table. 
IsEmpty i n t isEmptyO const 

Returns 1 if the hash table is empty; otherwise returns 0. 



TMIHashTablelteratorlmp template 



hashimp.h 



Implements an iterator for traversing TMIHashTablelmp containers. 



Public constructors 



Constructor 



TMIHashTablelteratorlmp! const TMIHashTableImp<T,A> & h ) 

Constructs an iterator object that traverses a TMIHashTablelmp container. 



Public member functions 



Current 



Restart 



T "Current () 

Returns a pointer to the current object. 

void Restart ( ) ; 

Restarts iteration from the beginning of the hash table. 



Operators 



operator int operator int() 

Converts the iterator to an integer value for testing if objects remain in the 
iterator. The iterator converts to if nothing remains in the iterator. 

operator ++ ■ T "operator ++ (int) 

Moves to the next object, and returns the object pointer that was current 
before the move (post-increment). 

T "operator ++ () 
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Moves to the next object, and returns the object pointer that was current 
after the move (pre-increment). 

TIHashTablelmp template hashimp.h 

Implements a hash table of pointers to objects of type T, using the system 
storage allocator TStandard Allocator. See TMIHashTablelmp on page 414 for 
members. 

Public constructors 

Constructor TIHashTablelmp ( unsigned aPrime = DEFAULT_HASH_TABLE_SIZE ) 

Constructs an indirect hash table that uses the system storage allocator. 

TIHashTablelteratorlmp template hashimp.h 

Implements an iterator object that traverses TIHashTablelmp containers, and 
uses the system memory allocator TStandard Allocator. See 
TMIHashTablelteratorlmp on page 415 for members. 

Public constructors 

Constructor TIHashTablelteratorlmp ( const TIHashTableImp<T> & h ) 

TMListElement template listimp.h 

This class defines the nodes for TMListlmp and TMIListlmp and related 
classes. 

Public data members 

data T Data; 

Data object contained in the list. 

Next TMListElement<T,Alloc> *Next; 

A pointer to the next element in the list. 
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Public constructors 



Constructor 



Constructor 



operator delete 
operator new 



TMListElement ( ) ; 

Constructs a list element. 

TMListElement ( T& t, TMListElement<T,Alloc> *p ) 

Constructs a list element, and places it after the object at location p. 



Operators 



void operator delete ( void * ); 
Deletes an object. 

void *operator new( size_t sz ) ; 

Allocates a memory block of sz amount, and returns a pointer to the 
memory block. 



TMListlmp template 



listimp.h 



Implements a managed list of objects of type T. TMListlmp assumes that T 
has meaningful copy semantics, and a default constructor. 



CondFunc 



IterFunc 



Constructor 



Type definitions 



typedef int ( *CondFunc) (const T &, void *); 

Function type used as a parameter to FirstThat and LastThat member 
functions. 

typedef void ( *IterFunc) (T &, void *); 

Function type used as a parameter to ForEach member function. 

Public constructors 

TMListlmp () 

Constructs an empty list. 
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Public member functions 



Add 



Detach 



FirstThat 



Flush 



ForEach 



IsEmpty 



LastThat 



PeekHead 



int Add( const T& t ); 
Adds an object to the list. 

int Detach (const T&, int = ); 

Removes the given object from the list. Returns for failure, 1 for success in 
removing the object. The second argument specifies whether the object 
should be deleted. See TShouldDelete on page 460. 

T *FirstThat( int ( *) (const T &, void *), void * ) const; 

Returns a pointer to the first object in the list that satisfies a given 
condition. You supply a test-function pointer /that returns true for a certain 
condition. You can pass arbitrary arguments via args. Returns if no object 
in the array meets the condition. 

See also: LastThat 

void Flush ( int del = ); 

Flushes the list without destroying it. 

int Detach ( const T&, int = ); 
void ForEach (IterFunc, void * ); 

Executes function / for list element. ForEach creates an internal iterator to 
execute the given function for each element in the array. The args argument 
lets you pass arbitrary data to this function. 

int IsEmpty () const 

Returns 1 if the list has no elements; otherwise returns 0. 

T *LastThat( int ( *) (const T &, void *), void * ) const; 

Returns a pointer to the last object in the list that satisfies a given condition. 
You supply a test function pointer, /, that returns true for a certain 
condition. You can pass arbitrary arguments via args. Returns if no object 
in the array meets the condition. Note that LastThat creates its own internal 
iterator, so you can treat it as a "search" function. 

See also: FirstThat, ForEach 

Const T& PeekHead () const 

Returns a reference to the Head item in the list, without removing it. 
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Protected data members 



Head, Tail 



TMListElement<T,Alloc> Head, Tail; 

The elements before the first and after the last elements in the list. 



Protected member functions 



FindDetach virtual TMListElement<T,Alloc> *FindDetach( const T& t ) 

Determines whether an object is in the list, and returns a pointer to its 
predecessor. Returns if not found. 

FindPred virtual TMListElement<T,Alloc> *FindPred( const T& ) ; 

Finds the element that would be followed by the parameter. The function 
does not check whether the parameter is actually there. This can be used for 
inserting (insert after returned element pointer). 



TMListlteratorlmp template 



listimp.h 



Implements a list iterator that works on direct, managed list. For indirect 
list iteration see TMIListlteratorlmp on page 422. 



Public constructors 



Constructor 



TMListlteratorlmp (const TMListImp<T,Alloc> &1) 
Constructs an iterator that traverses TMListlmp objects. 



Public member functions 



Current 



Restart 



operator int 



Const T& Current () 

Returns the current object. 

void Restart () 

Restarts iteration from the beginning of the list. 

Operators 



operator int ( ) ; 
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Converts the iterator to an integer value for testing if objects remain in the 
iterator. The iterator converts to if nothing remains in the iterator. 

operator ++ const T& operator ++ ( int ) 

Moves to the next object, and returns the object that was current before the 
move (post-increment). 

Const T& operator ++ () 

Moves to the next object, and returns the object that was current after the 
move (pre-increment). 

TListlmp template listimp.h 

Implements a list of objects of type T. TListlmp assumes that T has 
/ meaningful copy semantics, and a default constructor. See TMListlmp on 

page 41 7 for members. 

TListlteratorlmp template listimp.h 

Implements a list iterator that works on direct, managed list. See 
TMListlteratorlmp on page 419 for members. 

Public constructors 

Constructor TListlteratorlmp ( const TMListImp<T,TStandardAllocator> &1 ) 

Constructs an iterator that traverses TListlmp objects. 

TMSListlmp template listimp.h 

Implements a managed, sorted list of objects of type T. TMSListlmp 
assumes that T has meaningful copy semantics, a meaningful < operator, 
and a default constructor. See TMListlmp on page 417 for members. 

TMSListlteratorlmp template listimp.h 

Implements a list iterator that works on direct, managed, sorted list. See 
TMListlteratorlmp on page 419 for members. 
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Public constructors 



Constructor 



TMSListIteratorImp(. const TMSListImp<T,Alloc> &1 ) 
Constructs an iterator that traverses TMSListlmp objects. 



TSListlmp template 



listimp.h 



Implements a sorted list of objects of type T, using TStandardAllocator for 
memory management. TSListlmp assumes that T has meaningful copy 
semantics, a meaningful < operator, and a default constructor. See 
TMListlmp on page 417 for members. 



TSListlteratorlmp template 



listimp.h 



Implements a list iterator that works on direct, sorted list. See 
TMListlteratorlmp on page 419 for members. 



TMIListlmp template 



listimp.h 



Implements a managed list of pointers to objects of type T. Since pointers 
always have meaningful copy semantics, this class can handle any type of 
object. 



CondFunc 



IterFunc 



Type definitions 



typedef int ( *CondFunc) (const T &, void *); 

Function type used as a parameter to FirstThat and LastThat member 
functions. 

typedef void ( *IterFunc) (T &, void *); 

Function type used as a parameter to ForEach member function. 



Public member functions 



Add 



int Add( T *t ); 

Adds an object pointer to the list. 
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Detach 



FirstThat 



ForEach 



LastThat 



PeekHead 



int Detach ( T *t, int del = ) 

Removes the given object pointer from the list. The second argument 
specifies whether the object should be deleted. See TShouldDelete on 
page 460. 

T *FirstThat( int. ( *) (const T &, void *), void * ) const? 

Returns a pointer to the first object in the list that satisfies a given 
condition. You supply a test-function pointer /that returns true for a certain 
condition. You can pass arbitrary arguments via args. Returns if no object 
in the array meets the condition. 

See also: LastThat 

void ForEach (IterFunc, void * ) 

Executes function / for each list element. ForEach creates an internal iterator 
to execute the given function for each element in the array. The args 
argument lets you pass arbitrary data to this function. 

T *LastThat( int ( *) (const T &, void *)> void * ) const; 

Returns a pointer to the last object in the list that satisfies a given condition. 
You supply a test function pointer, /, that returns true for a certain 
condition. You can pass arbitrary arguments via args. Returns if no object 
in the array meets the condition. Note that LastThat creates its own internal 
iterator, so you can treat it as a "search" function. 

See also: FirstThat, ForEach 

T *PeekHead() const 

Returns the object pointer at the Head of the list, without removing it. 



Protected member functions 



FindPred 



virtual TMListElement<VoidPointer,Alloc> *FindPred( VoidPointer ); ' 

Finds the element that would be followed by the parameter. The function 
does not check whether the parameter is actually there. This can be used for 
inserting (insert after returned element pointer). 



TMIListlteratorlmp template 



listimp.h 



Implements a list iterator that works with any managed indirect list. For 
direct lists, see TMListlteratorlmp on page 419. 
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Public constructors 



Constructor 



TMIListIteratorImp( const TMIListImp<VoidPointer,Alloc> &1 
Constructs an object that iterates on TMIListlmp objects. 



Public member functions 



Current 



Restart 



T *Current() 

Returns the current object pointer. 

void Restart () 

Restarts iteration from the beginning of the list. 



Operators 



operator ++ T Operator ++ (int) 

Moves to the next object, and returns the object that was current before the 
move (post-increment). 

T *operator ++ () 

Moves to the next object, and returns the object that was current after the 
move (pre-increment). 



TIListlmp template 



listimp.h 



Implements a list of pointers to objects of type T. Since pointers always 
have meaningful copy semantics, this class can handle any type of object. 
See TMIListlmp on page 421 for members. 



TIListlteratorlmp template 



listimp.h 



Implements a list iterator that works with any indirect list. See 
TMIListlteratorlmp on page 422 for members. 

Public constructors 



Constructor 



TIListlteratorlmp ( const TIListImp<T> &1 
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Constructs an object that iterates on TMIListlmp objects. 

TMISListlmp template listimp.h 

Implements a managed sorted list of pointers to objects of type T. Since 
pointers always have meaningful copy semantics, this class can handle any 
type of object. 

Public member functions 

In addition to the member functions described here, TMISListlmp inherits 
other member functions from TMIListlmp (see page 421). 

FindDetach virtual TMListElement<TVoidPointer,Alloc> *FindDetach(TVoidPointer) ; 

Determines whether an object is in the list, and returns a pointer to its 
predecessor. Returns if not found. 

FindPred virtual TMListElement<TVoidPointer,Alloc> *FindPred( TVoidPointer ); 

Finds the element that would be followed by the parameter. The function 
does not check whether the parameter is actually there. This can be used for 
inserting (insert after returned element pointer). 

TMISListlteratorlmp template listimp.h 

Implements a list iterator that works with any managed indirect list. For 
direct lists, see TMListlteratorlmp on page 419. 

Public constructors 

Constructor TMISListlteratorlmp! const TMISListImp<T,Alloc> &1 ) : 

Constructs an object that iterates on TMISListlmp objects. 

TISListlmp template listimp.h 

Implements a sorted list of pointers to objects of type T, using 
T Standard Allocator for memory management. Since pointers always have 
meaningful copy semantics, this class can handle any type of object. See 
TMISListlmp on page 424 for members. 
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TISListlteratorlmp template 



List containers 



listimp.h 



Implements a list iterator that works with any indirect list. See 
TMIListlteratorlmp on page 422 for members. 



Constructor 



Public constructors 



TISListlteratorlmp ( const TISListImp<T> ■ &1 ) 
Constructs an object that iterates on TISListlmp objects. 



TMQueueAsVector template 



queues.h 



Implements a managed queue of objects of type T, using a vector as the 
underlying implementation. TMQueueAsVector assumes T has meaningful 
copy semantics, a < operator, and a default constructor. 



Public constructors 



Constructor 



TMQueueAsVector ( unsigned sz = DEFAULT_QUEUE_SIZE ) 
Constructs a managed, vector-implemented queue, of sz size. 



Public member functions 



FirstThat 



Flush 



ForEach 



T *FirstThat(CondFunc, void *args ) const; 

Returns a pointer to the first object in the queue that satisfies a given 
condition. You supply a test-function pointer / that returns true for a certain 
condition. You can pass arbitrary arguments via args. Returns if no object 
in the array meets the condition. 

See also: LastThat 

void Flush ( TShouldDelete: :DeleteType = TShouldDelete: :Def Delete ) 

Flushes the queue without destroying it. The fate of any objects removed 
depends on the current ownership status and the value of the dt argument. 

See also: TShouldDelete: :ownsElements 

void ForEach (IterFunc, void *args ); 
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Executes function /for each queue element. ForEach creates an internal 
iterator to execute the given function for each element in the array. The args 
argument lets you pass arbitrary data to this function. 



Get 



T Get i 



Removes the object from the end (tail) of the queue. If the queue is empty, it 
returns 0. Otherwise the removed object is returned. 

GetltemslnContainer i nt GetitemslnContainerO const 

Returns the number of items in the queue. 

int IsEmptyO const 

Returns 1 if the queue has no elements; otherwise returns 0. 

int IsFullf) const 

Returns 1 if the queue is full; otherwise returns 0. 

T *LastThat(CondFunc, void *args ) const; 

Returns a pointer to the last object in the queue that satisfies a given 
condition. You supply a test function pointer, /, that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. Note that LastThat creates its own 
internal iterator, so you can treat it as a "search" function. 

See also: FirstThat, ForEach 

void Put( T t ) 

Adds an object to (the tail of) a queue. 



IsEmpty 



IsFull 



LastThat 



Put 



TMQueueAsVectorlterator template 



queues.h 



Implements an iterator object for managed, vector-based queues. See 
TMDequeAsVectorlterator on page 385 for members. 

Public constructors 



Constructor 



TMQueueAsVectorlterator ( const TMDequeAsVector<T,Alloc> &q ) 
Constructs an object that iterates on TMQueueAsVector objects. 
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TQueueAsVector template 



Queue containers 



queues.h 



See TMQueueAsVector on page 425 for members. 



Public constructors 



Constructor • TQueueAsVector ( unsigned sz = DEFAULT_QUEUE_SIZE ) 

Constructs a vector-implemented queue, of sz size. 



TQueueAsVectorlterator template 



queues.h 



Constructor 



Implements an iterator object for vector-based queues. See 
TMDequeAsVectorlterator on page 385 for members. 

Public constructors 

TQueueAsVectorlterator ( const TQueueAsVector<T> &q ) 
Constructs an object that iterates on TQueueAsVector objects. 



TMIQueueAsVector template 



queues.h 



Implements a managed queue of pointers to objects of type T, using a 
vector as the underlying implementation. 



Public constructors 



Constructor TMIQueueAsVector ( unsigned sz = DEFAULT_QUEUE_SIZE 

Constructs a managed, indirect queue, of sz size. 



FirstThat 



Public member functions 



T *FirstThat(CondFunc, void *args ) const; 

Returns a pointer to the first object in the queue that satisfies a given 
condition. You supply a test-function pointer /that returns true for a certain 
condition. You can pass arbitrary arguments via args. Returns if no object 
in the array meets the condition. 
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Flush 



ForEach 



Get 



See also: LastThat 

void Flush ( TShouldDelete::DeleteType = TShouldDelete: :Def Delete ); 

Flushes the queue without destroying it. The fate of any objects removed 
depends on the current ownership status and the value of the dt argument. 

void ForEach (IterFunc, void *args );. 

Executes function /for each queue element. ForEach creates an internal 
iterator to execute the given function for each element in the array. The args 
argument lets you pass arbitrary data to this function. 

T *Get() 



Removes and returns the object pointer from the queue. If the queue is 
empty, it returns 0. 

GetltemslnContainer i nt GetltemsInContainerO const 



IsEmpty 



IsFull 



LastThat 



Put 



Returns the number of items in the queue. 

int IsEmptyO const 

Returns 1 if a queue has no elements; otherwise returns 0. 

int isFullO const ' 

Returns 1 if a queue is full; otherwise returns 0. 

T *LastThat(CondFunc, void *args ) const; 

Returns a pointer to the last object in the queue that satisfies a given 
condition. You supply a test function pointer, /, that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. Note that LastThat creates its own 
internal iterator, so you can treat it as a "search" function. 

See also: FirstThat, ForEach 

void Put( T *t ) 

Adds an object pointer to (the tail of) a queue. 



TMIQueueAsVectorlterator template 



queues.h 



Implements an iterator object for managed, indirect, vector-based queues. 
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Public constructors 



Constructor TMIQueueAsVectorIterator( const TMIDequeAsVector<T,Alloc> &q ) 

Constructs an object that iterates on TMIQueueAsVector objects. 

TIQueueAsVector template queues.h 

Implements a queue of pointers to objects of type T, using a vector as the 
underlying implementation. 

Public constructors 

Constructor TIQueueAsVector ( unsigned sz = DEFAULT_QUEUE_SIZE ) 

Constructs a indirect queue, of sz size. 

TIQueueAsVectorlterator template queues.h 

Implements an iterator object for indirect, vector-based queues. See 
TMDequeAsVectorlterator on page 385 for members. 

Public constructors 

Constructor TIQueueAsVectorlterator ( const TIQueueAsVector<T> &q ) 

Constructs an object that iterates on TIQueueAsVector objects. 

TMQueueAsDoubleList template queues.h 

Implements a managed queue of objects of type T, using a double-linked 
list as the underlying implementation. See TMDequeAsDoubleList on page 
390 for members. 

Public member functions 

FirstThat t *FirstThat(CondFunc ; void *args ) const 
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Flush 



ForEach 



Get 



Returns a pointer to the first object in the queue that satisfies a given 
condition. You supply a test-function pointer /that returns true for a certain 
condition. You can pass arbitrary arguments via args. Returns if no object 
in the array meets the condition. 

See also: LastThat 

void Flush ( int del ) 

Flushes objects from the queue. Flushes the queue without destroying it. 
The fate of any objects removed depends on the current ownership status 
and the value of the dt argument. 

void ForEach (IterFunc, void *args ) 

Executes function / for each queue element. ForEach creates an internal 
iterator to execute the given function for each element in the array. The args 
argument lets you pass arbitrary data to this function. 

T Get() 



Removes the object from the end (tail) of the queue. If the queue is empty, it 
returns 0. Otherwise the removed object is returned. 

GetltemslnContainer i nt GetltemsInContainerO const 

Returns the number of items in the queue. 

int IsEmptyO const - 

Returns 1 if a queue has no elements; otherwise returns 0. 

int IsFullO const 

Returns 1 if a queue is full; otherwise returns 0. 

T *LastThat(CondFunc, void *args ) const 

Returns a pointer to the last object in the queue that satisfies a given 
condition. You supply a test function pointer//, that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. Note that LastThat creates its own 
internal iterator, so you can treat it as a "search" function. 

See also: FirstThat, ForEach 

void Put( T t ) 

Adds an object to (the tail of) a queue. 



IsEmpty 



IsFull 



LastThat 



Put 
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TMQueueAsDoubleListlterator template queues.h 

Implements an iterator object for list-based queues. See 
TMDequeAsDoubleListlterator on page 392 for members. 

Public constructors 

Constructor TMQueueAsDoubleListlterator ( const TMQueueAsDoubleList<T,Alloc> & q ) 

Constructs an object that iterates on TMQueueAsDoubleList objects. 

TQueueAsDoubleList template queues.h 

Implements a queue of objects of type T, using a double-linked list as the 
underlying implementation. See TMQueueAsDoubleList on page 429 for 
members. 

TQueueAsDoubleListlterator template queues.h 

Implements an iterator object for list-based queues. See 
TMDequeAsDoubleListlterator on page 392 for members. 

Public constructors 

Constructor TQueueAsDoubleListlterator ( const ,TQueueAsDoubleList<T> &q ) 

Constructs an object that iterates on TQueueAsDoubleList objects. 

TMIQueueAsDoubleList template queues.h 

Implements a managed indirect queue of pointers to objects of type T, 
using a double-linked list as the underlying implementation. 

Public member functions 

FirstThat t *FirstThat(CondFunc, void *args ) const 

Returns a pointer to the first object in the queue that satisfies a given 
condition. You supply a test-function pointer /that returns true for a certain 
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condition. You can pass arbitrary arguments via args. Returns if no object 
in the array meets the condition. 

See also: LastThat 

Flush void Flush ( TShouldDelete::DeleteType dt = TShouldDelete: :Def Delete ) 

Flushes the queue without destroying it. The fate of any objects removed 
depends on the current ownership status and the value of the dt argument. 

ForEach vo i(j ForEachdterFunc, void *args ) 

Executes function /for each queue element. ForEach creates an internal 
iterator to execute the given function for each element in the array. The args 
argument lets you pass arbitrary data to this function. 

Get T *Get() 

Removes and returns the object pointer from the queue. If the queue is 
empty, it returns 0. 

GetltemslnContainer i nt GetltemsInContainerO const 

Returns the number of items in the queue. 
IsEmpty i n t isEmptyO const 

Returns 1 if the queue has no elements; otherwise returns 0. 
IsFull int IsFullO const 

Returns 1 if the queue is full; otherwise returns 0. 

LastThat t *LastThat(CondFunc, void *args ) const 

Returns a pointer to the last object in the dequeue that satisfies a given 
condition. You supply a test function pointer, /, that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. Note that LastThat creates its own 
internal iterator, so you can treat it as a "search" function. 

See also: FirstThat, ForEach 

Put void Put( T *t ) 

Adds an object pointer to (the tail of) a queue. 

TMIQueueAsDoubleLlstlterator template queues.h 

Implements an iterator object for indirect, list-based queues. See 
TMIDequeAsDoubleListlterator on page 394 for members. 
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Public constructors 



Constructor TMIQueueAsDoubleListIterator( const TMIQueueAsDoubleList<T,Alloc> & q ) 

Constructs an object that iterates on TMIQueueAsDoubleList objects. 

TIQueueAsDoubleList template queues.h 

Implements an indirect queue of pointers to objects of type T, using a 
double-linked list as the underlying implementation. See 
TMIQueueAsDoubleList on page 431 for members. 

TIQueueAsDoubleListlterator template queues.h 

Implements an iterator object for indirect, list-based queues. See 
TMIDequeAsDoubleListlterator on page 394 for members. 

Public constructors 

Constructor TIQueueAsDoubleListlterator ( const TIQueueAsDoubleList<T> & q ) 

Constructs an object that iterates on TIQueueAsDoubleList objects. 

TQueue template queues.h 

A simplified name for TQueue AsVector. 

TQueuelterator template queues.h 

A simplified name for TQueue AsVectorlterator. 

TMSetAsVector template sets.h 

Implements a managed set of objects of type T, using a vector as the 
underlying implementation. A set, unlike a bag, cannot contain duplicate 
items. 
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Public constructors 



Constructor TMSetAsVector ( unsigned sz = DEFAULT_SET_SIZE ) : 

Constructs an empty set. sz represents the number of items the set can hold. 



Public member functions 



In addition to the following member function, TMSetAsVector inherits 
member functions from TMBagAsVector. See TMBagAsVector on page 374 
for members. 

Add int Add( const T& t ) ; 

Adds an object to the set. 

TMSetAsVectorlterator template sets.h 

Implements an iterator object to traverse TMSetAsVector objects. See 
TMArrayAsVectorlterator on page 359 for members. 

Public constructors 

Constructor TMSetAsVectorlterator ( const TMSetAsVector<T,Alloc> &s ) : 

Constructs an object that iterates on TMSetAsVector objects. 

TSetAsVector template sets.h 

Implements a set of objects of type T, using a vector as the underlying 
implementation. TStandardAllocator is used to manage memory. See 
TMBagAsVector on page 374 for members. 

Public constructors 

Constructor TSetAsVector ( unsigned sz = DEFAULT_SET_SIZE ) : 

Constructs an empty set. sz represents the number of items the set can hold. 
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TSetAsVectorlterator template sets.h 

Implements an iterator object to traverse TSetAsVector objects. See 
TMArmyAsVectorltemtor on page 359 for members. 

Public constructors 

Constructor TSetAsVectorlterator ( const TSetAsVector<T> &s ) 

Constructs an object that iterates on TMSetAsVector objects. 

TMISetAsVector template sets.h 

Implements a managed set of pointers to objects of type T, using a vector as 
the underlying implementation. See TMIBagAsVector on page 376 for 
members. 

Public constructors 

Constructor TMISetAsVector ( unsigned sz = DEFAULT_SET_SIZE ) : 

Constructs an empty, managed, indirect set. sz represents the initial 
number of slots allocated. 

Public member functions 

In addition to the following member function, TMISetAsVector inherits 
member functions from TMIBagAsVector. See TMIBagAsVector on page 376. 

Add int Add( T * ); 

Adds an object pointer to the set. 

TMISetAsVectorlterator template sets.h 

Implements an iterator object to traverse TMISetAsVector objects. See 
TMIArrayAsVectorlterator on page 364 for members. 
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Public constructors 



Constructor TMISetAsVectorIterator( const TMISetAsVector<T,Alloc> &s ) 

Constructs an object that iterates on TMISetAsVector objects. 

TISetAsVector template sets.h 

Implements a set of pointers to objects of type T, using a vector as the 
underlying implementation. See TMIBagAsVector on page 376 for members. 

Public constructors 

Constructor TISetAsVector( unsigned sz = DEFAULT_SET_SIZE ) 

Constructs an empty, indirect bag. sz represents the initial number of slots 
allocated. 

TISetAsVectorlterator template sets.h 

Implements an iterator object to traverse TISetAsVector objects. See 
TMIArrayAsVectorlterator on page 364 for members. 

Public constructors 

Constructor TISetAsVectorlteratorf const TISetAsVector<T> &s ) 

Constructs an object that iterates on TISetAsVector objects. 

TSet template sets.h 

A simplified name for TSetAsVector. 

TSetlterator template sets.h 

A simplified name for TSetAsVectorlterator. 
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TMStackAsVector template 



stacks.h 



Implements a managed stack of objects of type T, using a vector as the 
underlying implementation. 

Type definitions 



CondFunc 



IterFunc 



typedef int ( *CondFunc) (const T &, void *); 

Function type used as a parameter to FirstThat and LastThat member 
functions. 

typedef void ( *IterFunc) (T &, void *); 

Function type used as a parameter to ForEach member function. 



Public constructors 



Constructor 



TMStackAsVector ( unsigned max = DEFAULT_STACK_SIZE ) 

Constructs a managed, vector-implemented stack, with max indicating the 
maximum stack size. 



Public member functions 



FirstThat 



Flush 



ForEach 



T *FirstThat (CondFunc, void *args ) const 

Returns a pointer to the first object in the stack that satisfies a given 
condition. You supply a test-function pointer / that returns true for a certain 
condition. You can pass arbitrary arguments via args. Returns if no object 
in the array meets the condition. 

See also: LastThat 

void Flushf TShouldDelete::DeleteType = TShouldDelete: :DefDelete ) 

Flushes the stack without destroying it. The fate of any objects removed 
depends on the current ownership status and the value of the dt argument. 

See also: TShouldDelete::ownsElements 

void ForEach (IterFunc, void *args ) 

Executes function /for each stack element. ForEach creates an internal 
iterator to execute the given function for each element in the array. The args 
argument lets you pass arbitrary data to this function. 
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IsEmpty 



IsFull 



LastThat 



GetltemslnContainer int GetltemsInContainerO const 

Returns the number of items in the stack. 

int IsEmpty () const 

Returns 1 if the stack has no elements; otherwise returns 0. 

int IsFull () const 

Returns 1 if the stack is full; otherwise returns 0. 

T *LastThat( int ( * f) (const T &, void *), void *args ) const 

Returns a pointer to the last object in the stack that satisfies a given 
condition. You supply a test function pointer, /, that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. Note that LastThat creates its own 
internal iterator, so you can treat it as a "search" function. 

See also: FirstThat, ForEach 

T Pop() 

Removes the object from the top of the stack and returns the object. The fate 
of the popped object is determined by ownership. See TShouldDelete on 
page 460. 

void Push( const T& t ) 

Pushes an object on the top of the stack. 

Const T& Top() const 

Returns but does not remove the object at the top of the stack. 



Pop 



Push 



Top 



TMStackAsVectorlterator template 



stacks.h 



Implements an iterator object for managed, vector-based stacks. See 
TMVectorlteratorlmp on page 447 for members. N 

Public constructors 



Constructor 



TMStackAsVectorlterator ( const TMStackAsVector<T,Alloc> & s 
Constructs an object that iterates on TMStackAsVector objects. 
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TStackAsVector template stacks.h 

Implements a stack of objects of type T, using a vector as the underlying 
implementation, and TStandardAUocator for memory management. 

Public constructors 

Constructor TStackAsVector ( unsigned max = DEFAULT_STACK_SIZE ) 

Constructs a vector-implemented stack, with max indicating the maximum 
stack size. 

TStackAsVectorlterator template stacks.h 

Implements an iterator object for managed, vector-based stacks. See 
TMVectorlteratorlmp on page 447 for members. 

Public constructors 

Constructor TStackAsVectorlterator ( const TStackAsVector<T> & s ) : 

Constructs an object that iterates on TStackAsVector objects. 

TMIStackAsVector template stacks.h 

TMIStackAsVector implements a managed stack of pointers to objects of 
type T, using a vector as the underlying implementation. 

Type definitions 

CondFunc typedef int ( *CondFunc) (const T &, void *); 

Function type used as a parameter to FirstThat and LastThat member 
functions. 

IterFunc typedef void ( *IterFunc) (T &, void *); 

Function type used as a parameter to ForEach member function. 
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Public constructors 



Constructor 



TMIStackAsVector( unsigned max = DEFAULT_STACK_SIZE ) 

Constructs a managed, indirect, vector-implemented stack, with max 

indicating the maximum stack size. 



Public member functions 



FirstThat 



Flush 



ForEach 



T *FirstThat(CondFunc, ■ void *args ) const 

Returns a pointer to the first object in the stack that satisfies a given 
condition. You supply a test-function pointer / that returns true for a certain 
condition. You can pass arbitrary arguments via args. Returns if no object 
in the array meets the condition. 

See also: LastThat 

void Flush ( TShouldDelete::DeleteType = TShouldDelete: :Def Delete •) 

Flushes the stack without destroying it. The fate of any objects removed 
depends on the current ownership status and the value of the dt argument. 

See also: TShouldDelete::ownsElements 

void ForEach (IterFunc, void *args ) 



Executes function / for each stack element. ForEach creates an internal 
iterator to execute the given function for each element in the array. The args 
argument lets you pass arbitrary data to this function. 

GetltemslnContainer i nt GetltemsInContainerO const 



IsEmpty 



IsFull 



LastThat 



Returns the number of items in the stack. 

int IsEmpty () const 

Returns 1 if the stack has no elements; otherwise returns 0. 

int IsFull () const 

Returns 1 if the stack is full; otherwise returns 0. 

T *LastThat( CondFunc, void *args ) const 

Returns a pointer to the last object in the stack that satisfies a given 
condition. You supply a test function pointer, /, that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
object in the array meets the condition. Note that LastThat creates its own 
internal iterator, so you can treat it as a "search" function. 

See also: FirstThat, ForEach 
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Pop T *Pop() 

Removes the object from the top of the stack and returns a pointer to the 
object. The fate of the popped object is determined by ownership. See 
TShouldDelete on page 460. 

Push void Push( T *t ) 

Pushes a pointer to an object on the top of the stack. 
Top T *Top() const 

Returns but does not remove the object pointer at the top of the stack. 

TMIStackAsVectorlterator template stacks.h 

Implements an iterator object for managed, indirect, vector-based stacks. 
See TMVectorlteratorlmp on page 447 for members. 

Public constructors 

Constructor TMIStackAsVectorlterator ( const TMIStackAsVector<T,Alloc> & s ) 

Constructs an object that iterates on TMIStackAsVector objects. 

TIStackAsVector template stacks.h 

Implements an indirect stack of pointers to objects of type T, using a vector 
as the underlying implementation. See TMIStackAsVector on page 439 for 
members. 

Public constructors 

Constructor TIStackAsVector( unsigned max = DEFAULT_STACK_SIZE ) : 

TMIStackAsVector<T,TStandardAllocator>( max ) 

Constructs an indirect, vector-implemented stack, with max indicating the 
maximum stack size. 
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TIStackAsVectorlterator template stacks.h 

Implements an iterator object for indirect, vector-based stacks. See 
TMIVectorlteraiorlmp on page 455 for members. 

Public constructors 

Constructor TMIStackAsVectorIterator( const TMIStackAsVector<T,Alloc> & s ) 

Constructs an object that iterates on TIStackAsVector objects. 

TMStackAsList template stacks.h 

Implements a managed stack of objects of type T, using a list as the 
underlying implementation. See TMStackAsVector on page 437 for 
members. 

TMStackAsListlterator template stacks.h 

Implements an iterator object for managed, list-based stacks. See 
TMListlteratorlmp on page 419 for members. 

Public constructors 

Constructor TMStackAsListlterator ( const TMStackAsList<T,Alloc> & s ) : 

TMListIteratorImp<T,Alloo(s.Data) . 

Constructs an object that iterates on TMStackAsList objects. 

TStackAsList template stacks.h 

Implements a managed stack of objects of type T, using a list as the 
underlying implementation. See TMStackAsVector on page 437 for 
members. 
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TStackAsListlterator template stacks.h 

Implements an iterator object for list-based stacks. See TMVectorlteratorlmp 
on page 447 for members. 

Public constructors 

Constructor TStackAsListlterator ( const TStackAsList<T> & s ) : 

TMStackAsListIterator<T, TStandardAllocatoo (s) 

Constructs an object that iterates on TIStackAsVector objects. 

TMIStackAsList template stacks.h 

Implements a managed stack of pointers to objects of type T, using a linked 
list as the underlying implementation. See TMIStackAsVector on page 439 
for members. 

TMIStackAsListlterator template stacks.h 

Implements an iterator object for managed, indirect, list-based stacks. See 
TMIListlteratorlmp on page 422 for members. 

Public constructors 

Constructor TMIStackAsListlterator ( const TMIStackAsList<T,Alloc> & s ) 

Constructs an object that iterates on TMIStackAsList objects. 

TIStackAsList template stacks.h 

Implements TMIStackAsList with the standard allocator T Standard Allocator. 
See TMIStackAsVector on page 439 for members. 

TIStackAsListlterator template stacks.h 

Implements an iterator object for indirect, list-based stacks. See 
TMIVectorlteratorlmp on page 455 for members. 
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Public constructors 



Constructor 



TIStackAsListIterator( const TIStackAsList<T> & s ) 
Constructs an object that iterates on TIStackAsList objects. 



TStack template 



stacks.h 



A simplified name for TStackAsVector. 



TStacklterator template 



stacks.h 



A simplified name for TStackAsVectorlterator. 



TMVectorlmp template 



vectimp.h 



Implements a managed vector of objects of type T. TMVectorlmp assumes 
that T has meaningful copy semantics, and a default constructor. 



Type definitions 



CondFunc 



IterFunc 



Constructor 



Constructor 



Constructor 



typedef int ( *CondFunc) (const T &, void *); 

Function type used as a parameter to FirstThat and LastThat member 
functions. 

typedef void ( *IterFunc) (T &, void *); 

Function type used as a parameter to ForEach member function. 

Public constructors 

TMVectorlmp ( ) ; 

Constructs a vector with no entries. 

TMVectorlmp ( unsigned sz, unsigned = 0); 

/ 
Constructs a vector of sz objects, initialized by default to 0. 

TMVectorImp( const TMVectorImp<T,Alloc> & ) ; 

Constructs a vector copy. 
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Public member functions 



FirstThat 



Flush 



ForEach 



GetDelta 



LastThat 



T *FirstThat(CondFunc, void *args ) const 

Returns a pointer to the first object in the vector that satisfies a given 
condition. You supply a test-function pointer / that returns true for a certain 
condition. You can pass arbitrary arguments via args. Returns if no object 
in the array meets the condition. 

T *FirstThat(CondFunc, void *, unsigned, unsigned ) const; 

This version of FirstThat allows you to specify a range to be searched. 
Returns a pointer to the first object in the vector that satisfies a given 
condition. You supply a test-function pointer /that returns true for a certain 
condition. You can pass arbitrary arguments via args. Returns if no object 
in the array meets the condition. 

See also: LastThat 

void Flush( unsigned = 0, unsigned = UINT_MAX, unsigned = ) ; 

Flushes the vector without destroying it. The fate of any objects removed 
depends on the current ownership status and the value of the first 
argument. A range to be flushed can be specified with the last two 
arguments. 

See also: TShouldDelete::ownsElements 

void ForEach (IterFunc, void *args ) 

Returns a pointer to the first object in the vector that satisfies a given 
condition. ForEach creates an internal iterator to execute the given function 
for each element in the array. The args argument lets you pass arbitrary 
data to this function. 

void ForEach (IterFunc, void *, unsigned, unsigned ); 

This version allows you to specify a range. 

See also: LastThat 

virtual unsigned GetDelta ( ) const; 

Returns the growth delta for the array. 

T *LastThat( CondFunc, void *args ) const 

Returns a pointer to the last object in the vector that satisfies a given 
condition. You supply a test function pointer, /, that returns true for a 
certain condition. You can pass arbitrary arguments via args. Returns if no 
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Limit 



Resize 



Top 



object in the array meets the condition. Note that LastThat creates its own 
internal iterator, so you can treat it as a "search" function. 

T *LastThat( CondFunc, void *, unsigned, unsigned ) const; 

This version allows you to specify a range. 

See also: FirstThat, ForEach 

unsigned Limit () const; 

Returns the number of items that the vector can hold. 

void Resize ( unsigned sz, unsigned offset = ); 

Creates a new vector of size sz. The existing vector is copied to the 
expanded vector, then deleted. In a vector of pointers the entries are 
zeroed. In an array of objects the default constructor is invoked for each 
unused element, offset is the location in the new vector where the first 
element of the old vector should be copied. This is needed when the vector 
has to be extended downward. 

virtual unsigned Top() const; 

Returns the index of the current top element. For plain vectors Top returns 
Lim; for counted and sorted vectors Top returns the current insertion point. 



Operators 



operator [ ] 
operator = 



T & operator [] ( unsigned index ) const 

Returns a reference to the object at index. 

const TMVectorImp<T,Alloc> & operator = ( const TMVectorImp<T,Alloc> & 

Provides the vector assignment operator. 



Protected data members 



Lim 



unsigned Lim; 

Lim stores the upper limit for indexes into the vector. 



Protected member functions 



Zero 



virtual void Zero( unsigned, unsigned ) ' 

Provides for zeroing vector contents within the specified range. 
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TMVectorlteratorlmp template 



vectimp.h 



.Implements a vector iterator that works with any direct, managed vector of 
objects of type T. For indirect vector iterators, see TMIVectorlteratorlmp on 
page 455. 

Public constructors 



Constructor 



Constructor 



TMVectorlteratorlmp ( const TMVectorImp<T,Alloc> &v ) 

Creates an iterator object to traverse TMVectorlmp objects. 

TMVectorlteratorlmp! const TMVectorImp<T,Alloc> &v, unsigned start, 
unsigned stop ) 

Creates an iterator object to traverse TMVectorlmp objects. A range can be 
specified. 



Public member functions 



Current 



Restart 



Const T& Current ( ) ; 

Returns the current object. 

void Restart ( ) ; 

Restarts iteration over the whole vector. 

void Restart! unsigned start, unsigned stop ); 

Restarts iteration over the given range. 



Operators 



operator ++ const T& operator ++{int); 

Moves to the next object, and returns the object that was current before the 
move (post-increment). 

Const T& operator ++ ( ) ; 

Moves to the next object, and returns the object that was current after the 
move (pre-increment). 

operator int operator int ( ) ; 
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Converts the iterator to an integer value for testing if objects remain in the 
iterator. The iterator converts to if nothing remains in the iterator. 



TVectorlmp template 



vectimp.h 



Implements a vector of objects of type T. TVectorlmp assumes that T has 
meaningful copy semantics, and a default constructor. See TMVectorlmp on 
page 444 for members. 



Public constructors 



Constructor TVectorlmp ( ) 

Constructs a vector with no entries. 
Constructor TVectorlmp ( unsigned sz, unsigned = ) 

Constructs a vector of sz objects, initialized by default to 0. 
Constructor TVectorlmp ( const TVectorImp<T> &v ) 

Constructs a vector copy. 



TVectorlteratorlmp template 



vectimp.h 



Implements a vector iterator that works with any direct vector of objects of 
type T. See TMVectorlteratorlmp on page 447 for members. 



Public constructors 



Constructor TVectorlteratorlmp ( const TVectorImp<T> &v ) 

Creates an iterator object to traverse TVectorlmp objects. 

Constructor TVectorlteratorlmp ( const TVectorImp<T> &v, unsigned start, unsigned stop 

Creates an iterator object to traverse TVectorlmp objects. A range can be 
specified. 
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TMCVectorlmp template 



Vector containers 



vectimp.h 



Implements a managed, counted vector of objects of type T. TMCVectorlmp 
assumes that T has meaningful copy semantics, and a default constructor. 



Public constructors 



Constructor 



Constructor 



TMCVectorlmp ( ) ; 

Constructs a vector with no entries. 

TMCVectorlmp ( unsigned sz, unsigned = ); 

Constructs a vector of sz objects, initialized by default to 0. 



Public member functions 



Add 



AddAt 



Count 



Detach 



Find 



In addition to the member functions described here, TMCVectorlmp inherits 
member functions from TMVectorlmp (see page 444). 

int Add( const T& t ); 

Adds an object to the vector and increments Count_. 

int AddAt ( const T&, unsigned )'; 

Adds an object to the vector at the specified location, and increments 
Count _. 

unsigned Count ( ) const; 

Returns Count _. 

int Detach( unsigned, int dt = ) ; 
int Detach ( const T&, int dt = ) ; 

Remove by specifying the object or its index. The first version removes the 
object at loc, the second version removes the first object that compares equal 
to the specified object. The value of dt and the current ownership setting 
determine whether the object itself will be deleted. DeleteType is defined in 
the base class TShouldDelete as enum { NoDelete, Def Delete, Delete }.The 
default value of dt, NoDelete, means that the object will not be deleted 
regardless of ownership. With dt set to Delete, the object will be deleted 
regardless of ownership. If dt is set to DefDelete, the object will be deleted 
only if the array owns its elements. 

virtual unsigned Find ( const T& ) const; 
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GetDelta 



Finds the specified object and returns the object's index; otherwise returns 
INT_MAX. 

virtual unsigned GetDelta ( ) const; 

Returns Delta. 



Protected data members 



Count 



Delta 



In addition to the data members described here, TMCVectorlmp inherits 
data members from TMVectorlmp (see page 444). 

unsigned Counts- 
Maintains the number of objects in the vector. 
unsigned Delta; 
Specifies the size increment to be used when the vector grows. 



Protected member functions 



Top 



virtual unsigned Top( ) const 
Returns Count . 



TMCVectorlteratorlmp template 



vectimp.h 



Implements a vector iterator that works with any direct, managed, counted 
vector of objects of type T. See TMVectorlteratorlmp on page 447 for 
members. 



Public constructors 



Constructor TMCVectorIteratorImp( const TMCVectorImp<T ; Alloc> &v ) 

Creates an iterator object to traverse TMCVectorlmp objects. 

Constructor TMVectorlteratorlmp! const TMCVectorImp<T,Alloc> &v, unsigned start, 

unsigned stop ) . 

Creates an iterator object to traverse TMCVectorlmp objects. A range can be 
specified. 
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TCVectorlmp template 



Vector containers 



vectimp.h 



Implements a counted vector of objects of type T. TCVectorlmp assumes that 
T has meaningful copy semantics, and a default constructor. See 
TMCVectorlmp on page 449 for members. 



Public constructors 



Constructor 



Constructor 



TCVectorlmp ( ) ; 

Constructs a vector with no entries. 

MCVectorImp( unsigned sz, unsigned = ); 

Constructs a vector of sz objects, initialized by default to 0. 



TCVectorlteratorlmp template 



vectimp.h 



Implements a vector iterator that works with any direct, counted vector of 
objects of type T. See TMCVectorlteratorlmp on page 450 for members. 



Public constructors 



Constructor 



Constructor 



TCVectorlteratorlmp ( const TCVectorImp<T> &v ) 

Creates an iterator object to traverse TCVectorlmp objects. 

TCVectorlteratorlmp ( const TCVectorImp<T> &v, unsigned start, unsigned 
stop ) 

Creates an iterator object to traverse TCVectorlmp objects. A range can be 
specified. 



TMSVectorlmp template 



vectimp.h 



Implements a managed, sorted vector of objects of type T. TMSVectorlmp 
assumes that T has meaningful copy semantics, a meaningful < operator, 
and a default constructor. See TMCVectorlmp on page 449 for members. 
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Public constructors 



Constructor 



Constructor 



TMSVectorlmp ( ) 

Constructs a vector with no entries. 

TMSVectorlmp ( unsigned sz, unsigned d = ) 

Constructs a vector of sz objects, initialized by default to 0. 



TMSVectorlteratorimp template 



vectimp.h 



Implements a vector iterator that works with any direct, managed, sorted 
vector of objects of type T. See TMVectorlteratorlmp on page 447 for 
members. 



Public constructors 



Constructor 



Constructor 



TMSVectorlteratorimp ( const TMSVectorImp<T,Alloc> &v ) 

Creates an iterator object to traverse TMSVectorlmp objects. 

TMSVectorlteratorimp ( const TMSVectorImp<T ; Alloc> &v, unsigned start, 
unsigned stop ) 

Creates an iterator object to traverse TMSVectorlmp objects. A range can be 
specified. 



TSVectorlmp template 



vectimp.h 



Implements a sorted vector of objects of type T. TMSVectorlmp assumes 
that T has meaningful copy semantics, a meaningful < operator, and a 
default constructor. See TMCVectorlmp on page 449 for members. 



Constructor 



Constructor 



Public constructors 



TSVectorlmp ( ) 

Constructs a vector with no entries. 

TSVectorlmp ( unsigned sz, unsigned d = ) 

Constructs a vector of sz objects, initialized by default to 0. 
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TSVectorlteratorlmp template 



Vector containers 



vectimp.h 



Implements a vector iterator that works with any direct, sorted vector of 
objects of type T. See TMVectorlteratorlmp on page 447 for members. 



Public constructors 



Constructor 



Constructor 



TSVectorlteratorlmp ( const TSVectorImp<T> &v ) 

Creates an iterator object to traverse TSVectorlmp objects. 

TSVectorlteratorlmp! const TSVectorImp<T> &v, unsigned start, unsigned 
stop ) 

Creates an iterator object to traverse TSVectorlmp objects. A range can be 
specified. 



TMIVectorlmp template 



vectimp.h 



Implements a managed vector of pointers to objects of type T. Since 
pointers always have meaningful copy semantics, this class can handle any 
type of object. 



CondFunc 



IterFunc 



Type definitions 



typedef int ( *CondFunc) (const T &, void *); 

Function type used as a parameter to FirstThat and LastThat member 
functions. 

typedef void ( *IterFunc) (T ■&, void *); 

Function type used as a parameter to ForEach member function. 



Public constructors 



Constructor 



TMIVectorlmp ( unsigned sz ) ; 

Constructs a managed vector of pointers to objects, sz represents the vector 
size. 
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Public member functions 



FirstThat 



Flush 



ForEach 



GetDelta 



LastThat 



Limit 



Resize 



T * FirstThat (CondFunc, void *args ) const 

Returns a pointer to the first object in the vector that satisfies a given 
condition. You supply a test-function pointer /that returns true for a certain 
condition. You can pass arbitrary arguments via args. Returns if no object 
in the array meets the condition. 

T *FirstThat( int ( *) (const T &, void *), void *, unsigned, unsigned ) 
const; 

This version allows specifying a range to be searched. You supply a test- 
function pointer /that returns true for a certain condition. You can pass 
arbitrary arguments via args. Returns if no object in the array meets the 
condition. 

void Flush ( unsigned = 0, unsigned = UINT_MAX, unsigned = ); 

Flushes the vector without destroying it. The fate of any objects removed 
depends on the current ownership status and the value of the first 
argument. A range to be flushed can be specified with the last two 
arguments. 

void ForEach (IterFunc, void *args ) 

Returns a pointer to the first object in the vector that satisfies a given 
condition. See TMArrayAsVectorr.FirstThat. 

void ForEach (IterFunc, void *, unsigned, unsigned ); 

This version allows specifying a range. 

virtual unsigned GetDelta ( ) const; 

Returns the growth delta for the array. 

T *LastThat (CondFunc, void *args ) const 

Returns a pointer to the last object in the vector that satisfies a given 
condition. See TMArrayAsVector::LastThat. 

T *LastThat( CondFunc, void *, unsigned, unsigned ) const; 

This version allows specifying a range. 

unsigned Limit () const; 

Returns the number of items that the vector can hold. 

void Resize ( unsigned sz, unsigned offset = ); 
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Top 



Zero 



Creates a new vector of size sz. The existing vector is copied to the 
expanded vector, then deleted. In a vector of pointers the entries are 
zeroed. In an array of objects the default constructor is invoked for each 
unused element, offset is the location in the new vector where the first 
element of the old vector should be copied. This is needed when the vector 
has to be extended downward. 

virtual unsigned Top() const; 

Returns the index of the current top element. For plain vectors Top returns 
lira; for counted and sorted vectors Top returns the current insertion point. 

virtual void Zero( unsigned, unsigned ); 

Provides for zeroing vector contents within the specified range. 



Operators 



operator [ ] 



T * & operator [] ( unsigned index ) 

T * & operator [] ( unsigned index ) const 

Returns a reference to the object at index. 



TMIVectorlteratorlmp template 



vectimp.h 



Implements a vector iterator that works with an indirect, managed vector. 



Public constructors 



Constructor 



Constructor 



TMIVectorlteratorlmp ( const TMIVectorImp<T,Alloc> &v ) 
Creates an iterator object to traverse TMIVectorlmp objects. 

TMIVectorlteratorlmp! const TMIVectorImp<T,Alloc> &v, unsigned 1, unsigned u 

Creates an iterator object to traverse TMIVectorlmp objects. A range can be 
specified. 



Public member functions 



Current 



Restart 



T *Current(); 

Returns a pointer to the current object. 

void Restart ( ) ; 
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operator ++ 



operator int 



Restarts iteration over the whole vector. 

void Restart ( unsigned start, unsigned stop ) ; 
Restarts iteration over the given range. 

Operators 



Const T& operator ++(int); 

Moves to the next object, and returns the object that was current before the 
move (post-increment). 

Const T& operator ++(); 

Moves to the next object, and returns the object that was current after the 
move (pre-increment). 

operator int ( ) ; 

Converts the iterator to an integer value for testing if objects remain in the 
iterator. The iterator converts to if nothing remains in the iterator. 



TlVectorlmp template 



vectimp.h 



Implements a vector of pointers to objects of type T. Since pointers always 
have meaningful copy semantics, this class can handle any type of object. 
See TMIVectorlmp on page 453 for members. 

Public constructors 



Constructor 



TlVectorlmp ( unsigned sz, unsigned d = ) 

Constructs an indirect vector of sz size, with default initialization of 0. 



TlVectorlteratorlmp template 



vectimp.h 



Implements a vector iterator that works with an indirect, managed vector. 
See TMIVectorlteratorlmp on page 455 for members. 

Public constructors 



Constructor 



TlVectorlteratorlmp ( const TIVectorImp<T> &v 
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Creates an iterator object to traverse TlVectorlmp objects. 

Constructor TIVectorIteratorImp( const TIVectorImp<T> &v, unsigned 1, unsigned u ) 

Creates an iterator object to traverse TlVectorlmp objects. A range can be 
specified. 

TMICVectorlmp template vectimp.h 

Implements a managed, counted vector of pointers to objects of type T. 
Since pointers always have meaningful copy semantics, this class can 
handle any type of object. 

Public constructors 

Constructor TMICVectorlmp (unsigned sz, unsigned d = ) 

Constructs a managed, counted vector of pointers to objects, sz represents 
the vector size, d represents the initialization value. 

Public member functions 

In addition to the following member functions, TMICVectorlmp inherits 
other member functions and operators from TMIVectorlmp (see page 453). 

Add int Add( T *t ); 

Adds an object to the vector. 
Find unsigned Find( T *t ) const 

Finds the specified object pointer, and returns its index. 

Protected member functions 

Find virtual unsigned Find( void * ) const; 

Finds the specified pointer and returns its index. 
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TMICVectorlteratorlmp template vectimp.h 

Implements a vector iterator that works with an indirect, managed, 
counted vector. See TMIVectorlteratorlmp on page 455 and 
TMVectorlteratorlmp on page 447 for members. 



Public constructors 



Constructor TMICVectorlteratorlmp ( const TMICVectorImp<T,Alloc> &v ) 

Creates an iterator object to traverse TMCIVectorlmp objects. 

Constructor TMICVectorlteratorlmp ( const TMICVectorImp<T,Alloc> &v, unsigned 1, 

unsigned u ) 

Creates an iterator object to traverse TMICVectorlmp objects. A range can be 
specified. 

TlCVectorlmp template vectimp.h 

Implements a counted vector of pointers to objects of type T. Since pointers 
always have meaningful copy semantics, this class can handle any type of 
object. See TMICVectorlmp on page 457 for members. 

Public constructors 

Constructor TlCVectorlmp ( unsigned sz, unsigned d - ) 

Constructs a counted vector of pointers to objects, sz represents the vector 
size, d represents the initialization value. 

TlCVectorlteratorlmp template vectimp.h 

Implements a vector iterator that works with an indirect, managed, 
counted vector. See TMIVectorlteratorlmp on page 455 and 
TMVectorlteratorlmp on page 447 for members. 



Public constructors 



Constructor 



TlCVectorlteratorlmp ( const TICVectorImp<T> &v ) 
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Constructor 



Creates an iterator object to traverse TICVectorImp objects. 

TICVectorlteratorlmpf const TICVectorImp<T> &v, .unsigned 1, unsigned u ) 

Creates an iterator object to traverse TICVectorImp objects. A range can be 
specified. 



TMISVectorlmp template 



vectimp.h 



Implements a managed, sorted vector of pointers to objects of type T. Since 
pointers always have meaningful copy semantics, this class can handle any 
type of object. See TMICVectorlmp on page 457 for members. 

Public constructors 

Constructor TMISVectorImp( unsigned sz, unsigned d = ) ; 

Constructs a managed, sorted vector of pointers to objects, sz represents the 
vector size, d represents the initialization value. 



TMISVectorlteratorlmp template 



vectimp.h 



Implements a vector iterator that works with an indirect, managed, sorted 
vector. See TMIVectorlteratorlmp on page 455 and TMVectorlteratorlmp on 
page 447 for members. 

Public constructors 



Constructor 



Constructor 



TMISVectorlteratorlmp ( const TMISVectorImp<T,Alloc> &v ) 

Creates an iterator object to traverse TMIVectorlmp objects. 

TMISVectorlteratorlmp ( const TMISVectorImp<T,Alloc> &v, unsigned 1, 
unsigned u ) 

Creates an iterator object to traverse TMIVectorlmp objects. A range can be 
specified. 
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TlSVectorlmp template vectimp.h 

Implements a sorted vector of pointers to objects of type T. Since pointers 
always have meaningful copy semantics, this class can handle any type of 
object. See TMICVectorlmp on page 457 for members. 

Public constructors 

Constructor TlSVectorlmp ( unsigned sz, unsigned d = ) 

Constructs a managed, sorted vector of pointers to objects, sz represents the 
vector size, d represents the initialization value. 

TlSVectorlteratorlmp template vectimp.h 

Implements a vector iterator that works with an indirect, managed, sorted 
vector. See TMIVectorlteratorlmp on page 455 and TMVectorlteratorlmp on 
page 447 for members. 

Public constructors 

Constructor TISVectorIteratorImp( const TISVectorImp<T> &v ) 

Creates an iterator object to traverse TlSVectorlmp objects. 

Constructor TISVectorIteratorImp( const TISVectorImp<T> &v, unsigned 1, unsigned u ) 

Creates an iterator object to traverse TlSVectorlmp objects. A range can be 
specified. 

TShouldDelete class shddel.h 

TShouldDelete maintains the ownership state of an indirect container. The 
fate of objects that are removed from a container can be made to depend on 
whether the container owns its elements or not. Similarly, when a container 
is destroyed, ownership can dictate the fate of contained objects that are 
still in scope. As a virtual base class, TShouldDelete provides ownership 
control for all containers classes. The member function OwnsElements can 
be used either to report or to change the ownership status of a container. 
The member function DelObj is used to determine if objects in containers 
should be deleted or not. 
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Public data members 



enum DeleteType { NoDelete, DefDelete, Delete }; 

Enumerates values to determine whether or not an object should be deleted 
upon removal from a container. 



Public constructors 



Constructor 



TShouldDelete! DeleteType dt = Delete ) 

Creates a TShouldDelete object. See member function DelObj. 



Public member functions 



OwnsElements 



int OwnsElements () 

Returns 1 if the container owns its elements; otherwise returns 0. 

void OwnsElements! int del ) 

Changes the ownership status as follows: if del is 0, ownership is turned off; 
otherwise ownership is turned on. 



Protected member functions 



DelObj 



int DelObj ( DeleteType dt ) 

Tests the state of ownership and returns 1 if the contained objects should be 
deleted or if the contained elements should not be deleted. The factors 
determining this are the current ownership state, and the value of dt, as 
shown in the following table. 



OwnsElements 



delObj 
No Yes 



NoDelete 
DefDelete 
Delete 



No 
No 
Yes 



No 

Yes 

Yes 



delObj returns 1 if (dt is Delete) or (dt is DefDelete and the container currently 
owns its elements). Thus a dt of NoDelete returns (don't delete) regardless 
of ownership; a dt of Delete return 1 (do delete) regardless of ownership; 
and a dt of DefDelete returns 1 (do delete) if the elements are owned, but a 
(don't delete) if the objects are not owned. 
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The C++ mathematical classes 



This chapter describes Borland C++ mathematics based on C++ classes. 
These mathematical operations are available only in C++ programs. How- 
ever, a C++ program that uses any of these classes, the numerical types that 
the classes define, or any of the classes' friend and member functions can 
use any of ANSI C Standard mathematics routines. 

There are two classes, bed and complex, that construct numerical types. 
Along with these numerical types, each class defines the functions with 
which to carry out operations with their respective types (for example, 
converting to and from the bed and complex type). Each class also overloads 
all necessary operators. 

The mathematical classes are independent of any hierarchy. However, each 
class includes the iostream.h header file. 

The portability for bed and complex is as follows: 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 






■ 



bed 



bcd.h 



The class constructors create binary coded decimals (BCD) from integers or 
floating-point numerical types. The friend function real, described on page 
465, converts bed numbers to long double. 

Once you construct bed numbers, you can freely mix them in expressions 
with ints, doubles, and other numeric types. You can also use bed numbers 
in any of the ANSI C Standard mathematical functions. 

The following ANSI C math functions are overloaded to operate with bed 
types: 

friend bed abs(bcd&); 

friend bed acos(bcd &) ; . ' 

friend bed asin(bcd&); 
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bed 



Constructor 



Constructor 



friend bed atan(bcd &); 

friend bed cos (bed &); 

friend bed cosh(bcd&); 

friend bed exp(bcd &) ; 

friend bed log(bcd &); 

friend bed loglO(bcd&); 

friend bed pow(bcd & base, bed & expon) ; 

friend bed sin(bcd&); 

friend bed sinhfbed &); 

friend bed sqrt(bcd&); 

friend bed tan(bcd&); 

friend bed tanh(bcd&); 

See the documentation of these functions in Chapter 3. 

The bed class also overloads the operators +, -, *, /, +=, -=, *=, /=, =, ==, and 
!=. These operators provide bed arithmetic manipulation in the usual sense. 

The operators « and » are overloaded for stream input and output of bed 
numbers, as they are for other data types in iostream.h. 

bed numbers have about 17 decimal digits precision, and a range of about 
1 x lO" 125 to 1 x 10 125 . 

The number is rounded according to the rules of banker's rounding, which 
means round to nearest whole number, with ties being rounded to an even 
digit. 

Public constructors 

bcd(); 

The default constructor. You typically use this to declare a variable of type 
bed. 

bed i; // Construct a bed- type number. 

bed j = 37; // Construct and initialize a bed-type number. 

bcd(int x) ; 

This constructor defines a bed variable from an int variable or directly from 
an integer. 

int i = 15; 

bed j = bcd(i); // Initialize j with a previously declared type. 

bed k - bcd(12); // Construct k from the integer provided. 

The above example provides these variables: 

i = 15 j = 15 k = 12 
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Constructor bed (unsigned int x) ; 

This constructor defines a bed variable from a variable that was previously 
declared to be an unsigned int type. An unsigned integer can be provided 
directly to the constructor. 

Constructor bed ( long x); 

This constructor defines a bed variable from an long variable or directly 
from a long value. 

Constructor bed (unsigned long x); 

This constructor defines a bed variable from a variable that was previously 
declared to be an unsigned long type. 

Constructor bed (double x, int decimals = Max); 

This constructor defines a bed variable from a variable that was previously 
declared to be a floating point double type. The constructor also creates a 
variable directly from a double value. 

To specify a precision level (that is, the number of digits after the decimal 
point) that is different from the default, use the variable decimals; for 
example, 

double x = 1.2345; // Declare and initialize in the usual manner, 
bed y = bcd(x, 2); // Create a bed numerical type from x. 

The precision level for y is set to 2. Therefore, y is initialized with 1.23. 

Constructor bcdflong double x, int decimals - Max); 

This constructor defines a bed variable from a variable that was previously 
declared to be a floating point long double type. Alternately, you can 
supply a long double value directly in the place of x. 

To specify a precision level (that is, the number of digits after the decimal 
point) that is different from the default, use the variable decimals. 

Friend functions 



real 



long double real (bed number) 

You can use the real function to convert a binary coded decimal number 
back to a long double. See the Programmer's Guide, Chapter 2, for a discus- 
sion about arithmetic conversions. 
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complex 



complex.h 



Constructor 



Constructor 



Creates complex numbers. Once you construct complex numbers, you can 
freely mix them in expressions with ints, doubles, and other numeric types. 
You can also use complex numbers in any of the ANSI C Standard mathe- 
matical functions. The ANSI math functions are documented in Chapter 3. 

The complex class also overloads the operators +, - *, /, +=, -=, *=, /=, =, ==, 
and !=. These operators provide complex arithmetic manipulation in the 
usual sense. 

The operators « and » are overloaded for stream input and output of 
complex numbers, as they are for other data types in iostream.h. 

If you don't want to program in C++, but instead want to program in C, the 
only constructs available to you are struct complex and cabs, which give the 
absolute value of a complex number. Both of these alternates are defined in 
math.h. 

Public constructors 

complex(); 

The default constructor. You typically use this to declare a variable of type 
complex. 

complex i; // Construct a complex-type number. 

complex j - 37; // Construct and initialize a complex-type number. 

complex (double real, double imag = 0) ; 

Creates a complex numerical type out of a double. Upon construction, a real 
and an imaginary part are provided. The imaginary part is considered to be 
zero if imag is omitted. 

Friend functions 



abs 



acos 



friend double abs(complex& val) ; 

Returns the absolute value of a complex number. 

The complex version of abs returns a double. All other math functions 
return a complex type when val is complex type. 

friend complex acos(complex& z) ; 
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Calculates the arc cosine. 

The complex inverse cosine is defined by 

acos(z) = -i * log(z + i sqrt(l - z 2 )) . 

ar 9 double arg( complex x) ; 

arg gives the angle, in radians, of the number in the complex plane. 

The positive real axis has angle 0, and the positive imaginary axis has angle 
pi/2. If the argument passed to arg is complex (zero), arg returns zero. . 

arg(x) returns atan2(imag(x), real(x)). 

asin friend complex, asin(complex& z) ; 

Calculates the arc sine. 
The complex inverse sine is defined by 

asin(z) = -i * log(i * z + sqrt(l - z 2 )) 
3t3 n friend complex atan(complex& z) ; 

Calculates the arc tangent. 
The complex inverse tangent is defined by 

atan'(z) = -0.5 i log((l + i z)/(l - i z) ) 
con J complex conj (complex z) ; 

Returns the complex conjugate of a complex number. 

conj (z) is the same as complex (real (z) , -imag(z)). 

cos friend complex cos(complex& z) ; 

Calculates the cosine of a value. 

The complex cosine is defined by 

cos(z) = ( exp(i * z) + exp(-i * z) ) /■ 2 
COSh friend complex cosh(complex& z) ; 

Calculates the hyperbolic cosine of a value. 

The complex hyperbolic cosine is defined by 
cosh(z) = ( exp(z)'+ exp(-z) ) / 2 
ex P friend complex exp(complex& y) ; 

Calculates the exponential e to the y. 
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The complex exponential function is defined by 

exp(x + y * i) = exp(x) (cos(y) + i * sin(y) ) 

imag double imag (complex x) ; 

Returns the imaginary part of a complex number. 

The data associated to a complex number consists of two floating-point 
(double) numbers, imag returns the one considered to be the imaginary 
part. 

'°9 friend complex log(complex& z) ; 

Calculates the natural logarithm of z, 

The complex natural logarithm is defined by 

log(z) = log( abs(z) ) + i * arg(z) 
I09IO friend complex loglO(complex& z) ; 

Calculates log 10 (z). 
The complex common logarithm is defined by 

loglO(z) = log(z) / log(10) 
double norm (complex x); 



norm 



Returns the square of the absolute value. norm(x) returns the magnitude 
real(x) * real{x) + imag(x) * imag(x). 

norm can overflow if either the real or imaginary part is sufficiently large. 

P°' ar complex polar (double mag, double angle - 0); 

Returns a complex number with a given magnitude (absolute value) and 
angle. 

polar(mag, angle) is the same as complex(mag * cos(angle), mag * sin(angle)). 

P ow friend complex pow(complex& base, double expon) ; 

friend complex pow(double base, complex& expon); 
friend complex pow(complex& base, complex^ expon); 

Calculates base to the power of expon. 

The complex pow is defined by 

pow (base, expon) = exp( expon * log(Jbase)) 

double real (complex x) ; 

You can use the real function to convert a complex number back to a long 
double. The friend function returns the real part of a complex number or 
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complex 



converts a complex number back to double. The data associated to a 
complex number consists of two floating-point numbers, real returns the 
number considered to be the real part. / 

See the Programmer's Guide, Chapter 2, for a discussion about arithmetic 
conversions. 

sin friend complex sin(complex& z) ; 

Calculates the trigonometric sine. 

The complex sine is defined by 

sin(z) = ( exp(i * z) - exp(-i * z) ) / (2 * i) 
sm h friend complex sinh(complex& z) ; 

Calculates the hyperbolic sine. 

The complex hyperbolic sine is defined by 
sinh(z) = ( exp(z) - exp(-z) ) / 2 
sc |rt friend complex sqrt(complex& x) ; 

Calculates the positive square root. 

For any complex number x, sqrt(x) gives the complex root whose arg is 
arg(x)/2. 

The complex square root is defined by 

sqrt(x) = sqrt(abs(x) ) (cos( arg(x) / 2) + i * sin(arg(x)/2) ) 
t an friend complex tan(complex& z) ; 

Calculates the trigonometric tangent. 
The complex tangent is defined by 
tan(z) = sin(z) '/ cos(z) 
t an n friend complex tanh(complex& z) ; 

Calculates the hyperbolic tangent. 
The complex hyperbolic tangent is defined by 
tanh(z) = sinh(z) / cosh(z) 
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Borland provides a set of macros for debugging C++ code. These macros 
can be used with Windows and DOS and are located in checks.h. There are 
two types of macros, default and extended. The default macros are 

■ CHECK ■ TRACE 

■ PRECONDITION bWARN 

The extended macros are 

■CHECKX bTRACEX 

■ PRECONDITIONX hWARNX 

The default macros provide straightforward value checking and message 
output. The extended macros let you create macro groups that you can 
selectively enable or disable. Extended macros also let you selectively 
enable or disable macros within a group based on a numeric threshold 
level. 

Three preprocessor symbols control diagnostic macro expansion: 
__DEBUG, __TRACE, and __WARN. If one of these symbols is defined 
when compiling, then the corresponding macros expand and diagnostic 
code is generated. If none of these symbols is defined, then the macros do 
not expand and no diagnostic code is generated. These symbols can be 
defined on the command line using the -D switch, or by using #def ine 
statements within your code. 

The diagnostic macros are enabled according to the following table: 





__DEBUG=1 


__DEBUG=2 


__TRACE 


__WARN 


PRECONDITION 


X 


X 






PRECONDITIONX 


X 


X 






CHECK 




X 






CHECKX 




X 






TRACE 






X 




TRACEX 






X 




WARN 








X 


WARNX 








X 
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To create a diagnostic version of an executable, place the diagnostic macros 
at strategic points within the program code and compile with the 
appropriate preprocessor symbols defined/Diagnostic versions of the 
Borland class libraries are built in a similar manner. 

The following sections describe the default and extended diagnostic 
macros, give examples of their use, and explain message output and run- 
time control. 



Default diagnostic macros 



checks.h 



CHECK CHECK (<cond>) 

Outputs <cond> and throws an exception if <cond> equals 0. Use CHECK to 
perform value checking within a function. 

PRECONDITION PRECONDITION (<cond>) 

Outputs <cond> and throws an exception if <cond> equals 0. Use 
PRECONDITION on entry to a function to check the validity of the 
arguments and to do any other checking to determine if the function has 
been invoked correctly. 

TRACE TRACE (<msg>) 

Outputs <msg>. TRACE is used to output general messages that are not 
dependent on a particular condition. 

WARN WARN(<cond>,<msg>) 

Outputs <msg> if <cond> is nonzero. It is used to output conditional 
messages. 

Example The following program illustrates the use of the default TRACE and 
WARN macros: 

#include <checks.h> 

int main() 
{ 

TRACE (/'Hello World" ); 

WARN( 5 != 5, "Math is broken!" ); 

WARN( 5 != 7, "Math still works!" ); 

return ; > 

} - . . • 

When the above code is compiled with TRACE and __WARN defined, it 

produces the following output when run: 
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Trace PROG.C 5: [Def] Hello World 
Warning PROG.C 7: [Def] Math still works! 

The above output indicates that the message "Hello World" was output by 
the default TRACE macro on line 5 of PROG.C, and the message "Math still 
works!" was output by the default WARN macro on line 7 of PROG.C. 

Default diagnostic macros expand to extended diagnostic macros with the 
group set to "Def" and the level set to 0. This "Def" group controls the 
behavior of the default macros and is initially enabled with a threshold 
level of 0. 



Extended diagnostic macros 



checks.h 



CHECKX 



PRECONDITION 



TRACEX 



WARNX 



The extended macros CHECKX and PRECONDITIONX augment CHECK 
and PRECONDITION by letting you provide a message to be output when 
the condition fails. 

The extended macros TRACEX and WARNX augment TRACE and WARN 
by providing a way to specify macro groups that can be independently 
enabled or disabled. TRACEX and WARNX require additional arguments 
that specify the group to which the macros belongs, and the threshold level 
at which the macro should be executed. The macro is executed only if the 
specified group is enabled and has a threshold level that is greater than or 
equal to the threshold-level argument used in the macro. 

The following sections describe the extended diagnostic macros. 

CHECKX (<cond>,<msg>) 

Outputs <msg> and throws an exception if <cond> equals 0. Use CHECKX 
to perform value checking within a function. 

PRECONDITIONX (<cond>,<msg>) 

Outputs <msg> and throws an exception if <cond> equals 0. Use 
PRECONDITIONX on entry to a function to check the validity of the 
arguments and to do any other checking to determine if the function has 
been invoked correctly. 

TRACEX (<group>, <level>, <msg>) 

Trace only if <group> and <level> are enabled. 

WARNX ( <group> , <cond> , <level> , <msg> ) 

Warn only if <group> and <level> are enabled. 
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When using TRACEX and WARNX you need to be able to create groups. 
The following three macros create diagnostic macro groups: 

DIAG_DECLARE_GROUP DIAG_DECLARE_GROUP(<name>) 

Declare a group named <name>. 
DIAG_DEFINE_GROUP DIAG_DEFINE_GROUP(<name> / <enabled>,<level>) 

Define a group named <name>. 
DIAG_CREATE_GROUP DIAG_CREATE_GROUP(<name>,<enabled>,<level>) 

Define and declare a group named <name>. 



DIAG ENABLE 



The following two macros manipulate groups: 

DIAG_ENABLE (<group>, <state>) 
Sets <group>'s enable flag to <state>. 
DIAGJSENABLED DIAG_ISENABLED(<group>) 

Returns nonzero if <group> is enabled. 



DIAG SETLEVEL 



DIAG GETLEVEL 



Example 



The following two macros manipulate levels: 

DIAG_SETLEVEL (<group>, <level>) 

Sets <group>'s threshold level to <level>. 

DIAG_GETLEVEL ( <group> ) 

Gets <group>'s threshold level. 

Threshold levels are arbitrary numeric values that establish a threshold for 
enabling macros. A macro with a level greater than the group threshold 
level will not be executed. For example, if a group has a threshold level of 
(the default value), all macros that belong to that group and have levels of 1 
or greater are ignored. 

The following PROG.C example defines two diagnostic groups, Groupl and 
Group!, which are used as arguments to extended diagnostic macros: 

•#include' <checks.h> 

DIAG_CREATE_GROUP (Groupl , 1 , ) ; 
DIAG_CREATE_GROUP(Group2,l,0); 

int main( int argc, char **argv ) 

{ ' 

TRACE ( "Always works, argc=" « argc ); 

TRACEX ( Groupl, 0, "Hello" )'; 
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TRACEX( Group2, 0, "Hello" ); - ' 

DIAGJDISABLE (Groupl); 

TRACEX( Groupl, 0, "Won't execute - group is disabled!" ); 
TRACEX( Group2, 3, "Won't execute - level is too high!" ) ; 

return 0; 
} 

When the above code is compiled with TRACE defined and run, it 

produces the following output: 

Trace PROG.C 8: [Def] Always works, argc=l 
Trace PROG.C 10: [Groupl] Hello 
Trace PROG.C 11: [Group2] Hello 

Note that the last two macros are not executed. In the first case, the group 
Groupl is disabled. In the second case, the macro level exceeds Group2's 
threshold level (set by default to 0). 



Macro message output 



The CHECKX, PRECONDITION^ TRACE, TRACEX, WARN, and 
WARNX macros take a <msg> argument that is conditionally inserted into 
an output stream. This means a sequence of objects can be inserted in the 
output stream (for example TRACE ( "Mouse @ "« x « "," « y ); ). The 
use of streams is extensible to different object types and allows for 
parameters within trace messages. 

Diagnostic macro message output can be viewed while the program is 
running. If the target environment is Windows, the output is sent to the 
OutputDebugString function, and can be viewed with the DBWIN.EXE or 
OX.SYS utilities. If Turbo Debugger is running, the output will be sent to its 
log window. If the target environment is DOS, the output is sent to the 
standard error stream and can be easily redirected at the command line. 



Run-time macro control 



Diagnostic groups can be controlled at run time by using the control 
macros described above within your program or by directly modifying the 
group information within the debugger. 

This group information is contained in a template class named 
TDiagGroup< TDiagGroupClass##Group >, where ##Group is the name of the 
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group. This class contains a static structure Flags, which in turn contains the 
enabled flag and the threshold level. For example, to enable the group 
Groupl, you would set the variable 
TDiagGroup<TDiagGroupClassGroupl>::Flags.Enabled to 1. 
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Run-time support 



This chapter provides a detailed description, in alphabetical order, of 
functions and classes that provide run-time support. Any class operators or 
member functions are listed immediately after the class constructor. See the 
Programmer's Guide, Chapter 4, for a discussion of how to use exception- 
handling keywords. 

The portability for all classes and functions in this chapter is as follows: 



DOS 


UNIX 


Win 16 


Win 32 


ANSI C 


ANSI C++ 


OS/2 


■ 




■ 


■ 




■ 





Bad cast class 



typeinfo.h 



When dynamic_cast fails to make a cast to reference, the expression can 
throw Bad_cast. Note that when dynamic_cast fails to make a cast to 
pointer type, the result is the null pointer. 



Badjypeid class 



typeinfo.h 



When the operand of typeid is a dereferenced pointer, the typeid operator 
can throw Bad_typeid. 



set new handler function 



new.h 



typedef void (new * newjiandler) () throw (xalloc) ; 
new_handler set_new_handler(new_handler my_handler); 

set_new_handler installs the function to be called when the global operator 
new() or operator new[]() cannot allocate the requested memory. By default 
the new operators throw an xalloc exception if memory cannot be allocated. 
You can change this default behavior by calling set_new_handler to set a 
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new handler. To retain the traditional version of new, which does not throw 
exceptions, you can use set_new_handler(0). 

If new cannot allocate the requested memory, it calls the handler that was 
set by a previous call to setjiewjiandler. If there is no handler installed by 
setjiewjiandler, new returns 0. myjiandler should specify the actions to be 
taken when new cannot satisfy a request for memory allocation. The 
newjiandler type, defined in new.h, is a function that takes no arguments 
and returns void. A newjiandler can throw an xalloc exception. 

The user-defined myjiandler should do one of the following: 

■ Return after freeing memory 

■ Throw an xalloc exception or an exception derived from xalloc 

■ Call abort or exit functions 

If myjiandler returns, then new will again attempt to satisfy the request. 

Ideally, myjiandler frees up memory and returns; new can then satisfy the 
request and the program can continue. However, if myjiandler cannot 
provide memory for new, myjiandler must throw an exception or terminate 
the program. Otherwise, an infinite loop will be created. 

Preferably, you should overload operator new() and operator new[]() to 
take appropriate actions for your applications. 

setjiewjiandler returns the old handler, if one has been registered. 

The user-defined argument function, myjiandler, should not return a value. 

See also the description of abort, exit, and jiewjiandler (global variable). 

setjerminate function except.h 

typedef void ( *terminate_f unction) () ; 

terminate_function set_terminate(terminate_function t_func); 

setjerminate lets you install a function that defines the program's termina- 
tion behavior when a handler for the exception cannot be found. The 
, actions are defined in tjunc, which is declared to be a function of type 
terminate Junction. A terminate Junction type, defined in except.h, is a 
function that takes no arguments, and returns void. 

By default, an exception for which no handler can be found results in the 
program calling the terminate function. This will normally result in a call to 
abort. The program then ends with the message Abnormal program 
termination. If you want some function other than abort to be called by the 
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terminate function, you should define your own tjunc function. Your tjunc 
function is installed by setjerminate as the termination function. The instal- 
lation of tjunc lets you implement any actions that are not taken by abort. 

The previous function given to set_terminate will be the return value. 

The definition of tjunc must terminate the program. Such a user-defined 
function must not return to its caller, the terminate function. An attempt to 
return to the caller results in undefined program behavior. It is also an error 
for tjunc to throw an exception. 

See also the description of abort, set_unexpected, and terminate. 

set_unexpected function except.h 

typedef void ( * ,unexpected_function )(); 

unexpected_f unction set_unexpected(unexpected_f unction unexpected_func) ; 

setjmexpected lets you install a function that defines the program's behavior 
when a function throws an exception not listed in its exception specifica- 
tion. The actions are defined in unexpected June, which is declared to be a 
function of type unexpected Junction. An unexpected Junction type, defined in 
except.h, is a function that takes no arguments, and returns void. 

By default, an unexpected exception causes unexpected to be called. If 
unexpected June is defined, it is subsequently called by unexpected. Program 
control is then turned over to the user-defined unexpected June. Otherwise, 
terminate is called. 

The previous function given to setjmexpected will be the return value. 

The definition of unexpected June must not return to its caller, the unexpected 
function. An attempt to return to the caller results in undefined program 
behavior. 

unexpected June can also call abort, exit, or terminate. 

See also the description of abort, exit, setjerminate, and terminate. 

terminate function except.h 

void terminate () ; 

The function terminate can be called by unexpected or by the program when . 
a handler for an exception cannot be found. The default action by terminate 
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is to call abort. Such a default action causes immediate program 
termination. 

You can modify the way your program terminates when an exception is 
generated that is not listed in the exception specification. If you don't want 
the program to terminate with a call to abort, you can instead define a 
function to be called. Such a function (called a terminate Junction) will be 
called by terminate if it is registered with setjerminate. 

The function does not return. 

See also the description of abort and setjerminate. 



Typejnfo class 



typeinfo.h 



Provides information about a type. 



Public constructor 



Constructor None. 

Only a private constructor is provided. You cannot create Typejnfo objects. 

By declaring your objects to be rtti types, or by using the -RT compiler 

switch, the compiler provides your objects with the elements of Typejnfo. 

Typejnfo references are generated by the typeid operator. See Chapter 2 in 
the Programmer's Guide for a discussion of typeid. 



Operators 



operator == 
operator != 



int operator== (const Type_info &) const; 
Provides comparison of Typeinfos. 
int operator != (const Type_info &) const; 
Provides comparison of Typeinfos. 



Public member functions 



before 



int before (const Type_info &) ; - 

Use this function to compare the lexical order of types. For example, to 
compare two types, T1 and T2, use the following syntax: 
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fname 
name 



typeid( Tl ) .before (typeid( T2 ) ) ; 

The before function returns or 1. 

const char* far fname () const; 

const char* name() const; 

The functions, fname and name, perform identically. Use fname in large 
memory-model programs. 

Each of the functions returns a printable string that identifies the type name 
of the operand to typeid. The space for the character string is overwritten 
on each call. 



unexpected function 



except.h 



void unexpected!) ; 

The unexpected function is called when a function throws an exception not 
listed in its exception specification. The program calls unexpected, which by 
default calls any user-defined function registered by set_unexpected. If no 
function is registered with set_unexpected, the unexpected function then calls 
terminate. 

The unexpected function does not return. However, the function can throw 
an exception. 

See also the description of setjmexpected and terminate. 



xalloc class 



except.h 



Reports an error on allocation request. 

Public constructors 



Constructor xalloc (const string &msg, size_t size); 

The xalloc class has no default constructor. Every use of xalloc must define 
the message to be reported when a size allocation cannot be fulfilled. The 
string type is defined in cstring.h header file. 

Public member functions 



raise 



void raise () throw (xalloc ) ; 
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requested 



Calling raise causes an xalloc to be thrown. In particular, it throws *this. 

size_t requested () const;. 

Returns the number of bytes that were requested for allocation. 



xmsg class 



except.h 



Constructor 



Reports a message related to an exception. 

Public constructor 



xmsg (string msg) ; 

There is no default constructor for xmsg. Every xmsg object must have a 
string message explicitly defined. The string type is defined in cstring.h 
header file. 

Public member functions 



raise 



why 



void raise () throw(xmsg) ; 

Calling raise causes an xmsg to be thrown. In particular, it throws *this. 

string why() const; 

Reports the string used to construct an xmsg. Because every xmsg must 
have its message explicitly defined, every instance should have a unique 
message. 
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This chapter is a reference guide for the following classes, which are listed 
here with their associated header-file names: 

■ Date class (date.h) 

■ File classes (file.h) 

■ String classes (cstring.h) 

■ Threading classes (thread.h) 

■ Time classes (time.h) 

The header files for these classes are found in \BC4\INCLUDE or \BC4\ 
INCLUDEXCLASSLIB. 



TDate class 



date.h 



class TDate 

Class TDate represents a date. It has members that read, write, and store 
dates, and that convert dates to Gregorian calendar dates. 

Type definitions 

DayTy typedef unsigned DayTy; 

Day type. 
HowToPrint enum HowToPrint{ Normal, Terse, Numbers, EuropeanNumbers , European }; 

Lists different print formats. 
JulTy typedef unsigned long JulTy; 

Julian calendar type. 
Monthly typedef unsigned MonthTy; 

Month type. 
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YearTy 



Constructor 



Constructor 



Constructor 



Constructor 



Constructor 



AsString 
Between 
CompareTo 

Day 
DayName 



typedef unsigned YearTy; 
Year type. 

Public constructors 



TDateO; 

Constructs a TDate object with the current date. 

TDate ( DayTy day, YearTy year ); 

Constructs a TDate object with the given day and year. The base date for this 
computation is Dec. 31 of the previous year. If year == 0, it constructs a 
TDate with Jan. 1, 1901 as "day zero." For example, TDate(-l,0) = Dec. 31, 
1900 and TDate(l,0) = Jan. 2, 1901. 

TDate ( DayTy day, const char* month, YearTy year) ; 
TDate ( DayTy day, Monthly month, YearTy year) ; 

Constructs a TDate object for the given day, month, and year. 

TDate ( istreamk is ) ; 

Constructs a TDate object, reading the date from input stream is. 

TDate ( const TTime& time); 

Constructs a TDate object from TTime object time. 

Public member functions 

string AsString () const; 

Converts the TDate object to a string object. 

int Between ( const TDatek dl, const TDate& d2 ) const; 

Returns 1 if this TDate object is between dl and dl, inclusive. 

int CompareTo ( const TDate & ) const; 

Returns 1 if the target TDate is greater than parameter TDate, -1 if the target 
is less than the parameter, and if the dates are equal. 

DayTy Day() const; 

Returns the day of the year (1-365). 

const char *DayName ( DayTy weekDayNumber ) ; 
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DayOfMonth 
DayOfWeek 

DayslnYear 

DayWithinMonth 

FirstDayOfMonth 



Hash 



IndexOfMonth 



IsValid 



Jday 



Leap 



Max 



Returns a string name for the day of the week, where Monday is 1 and 
Sunday is 7. 

DayTy DayOfMonth () const; 

Returns the day of the month (1-31). 

DayTy DayOfWeek ( const char* dayName ) ; 

Returns the number associated with a string naming the day of the week, 
where Monday is 1 and Sunday is 7. 

DayTy DayslnYear ( YearTy ); . 

Returns the number of days in the specified year (365 or 366). 

int DayWithinMonth ( Monthly, DayTy, YearTy ); 

Returns 1 if the given day is within the given month for the given year. 

DayTy FirstDayOfMonth () const; 

Returns the number of the first day of the month for this TDate. 

DayTy FirstDayOfMonth ( Monthly month) const; 

Returns the number of the first day of a given month. Returns if month is 
outside the range 1 through 12. , 

unsigned Hash() const; 

Returns a hash value for the date. 

Monthly IndexOfMonth ( const char *monthName ) ; 

Returns the number (1-12) of the month monthname. 

int IsValid () const; 

Returns 1 if this TDate is valid, otherwise. 

JulTy Jday( Monthly, DayTy, YearTy ); 

Converts the given Gregorian calendar date to the corresponding Julian 
day number. Gregorian calendar started on Sep. 14, 1752. This function not 
valid before that date. Returns if the date is invalid. 

int LeapO const; 

Returns 1 if this TDate's year is a leap year, otherwise. 

TDate Max( const TDate& dt )' const; 

Compares this TDate with dt and returns the date with the greater Julian 
number. 
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Min 

Month 
MonthName 

NameOfDay 

NameOfMonth 

Previous 



TDate Min( const -TDatefc dt ) const; 

Compares this TDate with dt and returns the date with the lesser Julian 
number. 

MonthTy Month const; 

Returns the month number for this TDate. 

"const char *MonthName (. MonthTy monthNuraber ); 

Returns the string name for the given monthNumber (1-12). Returns for an 
invalid monthNumber. 

const char *NameOfDay() const; 

Returns this TDate's day string name. 

const char *NameOf Month ( ) const; 

Returns this TDate's month string name. 

TDate Previous ( const char *dayName ) const; 

Returns the TDate of the previous dayName. 

TDate Previous ( DayTy day ) const; 

Returns the TDate of the previous day. 

HowToPrint SetPrintOption(. HowToPrint h ); 

Sets the print option for all TDate objects and returns the old setting. See 
HowToPrint in the "Type definition" section for this class. 

DayTy WeekDayO const; 

Returns 1 (Monday) through 7 (Sunday). ' 

YearTy Year() const; 

Returns the year of this TDate. 

Protected member functions 



AssertlndexOfMonth static int AssertIndexOfMonth( MonthTy m ); 

Returns 1 if m is between 1 and 12 inclusive, otherwise returns 0. 
AssertWeekDayNumber static int AssertWeekDayNumber( DayTy d) ; 

Returns 1 if d is between 1 and 7 inclusive, otherwise returns 0. 



SetPrintOption 



WeekDay 



Year 
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Operators 

Operator < j. n t operator < ( const TDatek date ) const; 

Returns 1 if this TDate precedes date, otherwise returns 0. 
Operator <= i n t operator <= ( const TDatek date ) const; 

Returns 1 if this TDate is less than or equal to date, otherwise returns 0. 
Operator > j. n t operators ( const TDate& date ) const; 

Returns 1 if this TDate is greater than date, otherwise returns 0. 
Operator >= j_ n t operator >= ( const TDate& date ) const; 

Returns 1 if this TDate is greater than or equal to date, otherwise returns 0. 
Operator == i n t operator == ( const TDate& date ) const; 

Returns 1 if this TDate is equal to date, otherwise returns 0. 
Operator != i n t operator != ( const TDate& date ) const; 

Returns 1 if this TDate is not equal to date, otherwise returns 0. 
Operator- JulTy operator - ( const TDatek dt ) const; 

Subtracts dt from this TDate and returns the difference. 

Operator + friend TDate operator + ( const TDatek dt, int dd ) ; 

friend TDate operator + ( int dd, const TDatek dt ) ; 

Returns a new TDate containing the sum of this TDate and dd. 

Operator- friend TDate operator - ( const TDatek dt, int dd ); 

Subtracts dd from this TDate and returns the difference. 
Operator ++ void operator ++ ( ) ; 

Increments this TDate by 1. 
Operator-- void operator -- (); 

Decrements this TDate by 1. 
Operator += vo id operator += ( int dd ); 

Adds dd to this TDate. 
Operator -= void operator -= ( int dd ) ; 

Subtracts dd from this TDate. 
Operator « friend ostreamk operator « ( ostreamk os, const TDatek date ); 
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Inserts date into output stream os. 

Operator » friend istream& operator » ( istreamk is, TDate& date ); 

Extracts date from input stream is. 

TFileStatus structure file.h 

struct TFileStatus 
{ 

TTime createTime; 

TTime modifyTime; 

TTime accessTime; 

long size; 

uint8 attribute; 

char fullName[_MAX_PATH]; 
}; 

Describes a file record containing creation, modification, and access times; 
also provides the file size, attributes, and name. 

See also: TTime class 

TFile class file.h 

class TFile 

Class TFile encapsulates standard file characteristics and operations. 



FileNull 



File flags 



Public data members 



enum { FileNull 


}; 






Represents a null file handle. 




enum{ 








Readonly 


= 0_RD0NLY, 






ReadWrite 


= 0_RDWR, 






WriteOnly 


= 0_WR0NLY, 






Create 


= 0_CREAT I 


0_TRUNC, 


CreateExcl 


= 0_CREAT I 


0_ 


EXCL, 


Append 


= 0_APPEND, 
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#if defined! . 


_FLAT_ ) 


Compat 


= SH_COMPAT, 


DenyNone 


. = SH_DENYNONE, 


#else 




DenyRead 


= SHJDENYRD, 


DenyWrite 


= SH_DENYWR, 


#endif 




DenyRdWr 


= SH_DENYRW, 


Nolnherit 
}; 


= 0_NOINHERIT 



Enumerates file-translation modes and sharing capabilities. See the open 
and sopen functions in Chapter 3. 



enum{ 




PermRead 


= S_IREAD, 


PermWrite 


= S_IWRITE, 


PermRdWr 
}; 


= S_IREAD I S_IWRITE 



Enumerates file read and write permissions. See the creat function in 
Chapter 3. 

enum{ 

Normal = 0x00, 

RdOnly =0x01, 

Hidden = 0x02, 

System = 0x04, 

Volume = 0x08, 

Directory = 0x10, - 

Archive = 0x20 

Enumerates file types. 

enum seek_dir 
{ 

beg =0, 
cur =1, 

end = 2 ■ ■ 

}; 

Enumerates file-pointer seek direction. 
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Public constructors 



Constructor 



Constructor 



Constructor 



Constructor 



TFileO; 

Creates a TFile object with a file handle of FileNull. 

TFile ( int handle ); 

Creates a TFile object with a file handle of handle. 

TFile ( const TFile& file ) ; 

Creates a TFile object with the same file handle file. 

TFile ( const char* name, uintl6 access=ReadOnly, uintl6 
permission=PermRdWr ); 

Creates a TFile object and opens file name with the given attributes. The file 
is created if it doesn't exist. 



Public member functions 



Close 



Flush 



GetHandle 



GetStatus 



IsOpen 
Length 



int Close ( ) ; 

Closes the file. Returns nonzero if successful, otherwise. 

void Flush () ; 

Performs any pending I/O functions. 

int GetHandle () const; 
Returns the file handle. 

int GetStatus ( TFileStatusk status ) const; 

Fills status with the current file status. Returns nonzero if successful, 
otherwise. 

int GetStatus ( const char *namei TFileStatus& status ); 

Fills status with the status for file name. Returns nonzero if successful, 
otherwise. 

int IsOpen () const; 

Returns 1 if the file is open, otherwise. 

long Length () const; 
Returns the file length. 

void Length! long newLen ); 
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LockRange 



Open 



Position 



Read 



Remove 



Rename 



Seek 



SeekToBegin 



SeekToEnd 



SetStatus 



UnlockRange 



Write 



Resizes file to newLen. 

void LockRange ( long position, uint32 count ); 

Locks count bytes, beginning at position of the associated file. 

See also: UnlockRange 

int Open( const char* name, uintl6 access, uintl6 permission ); 

Opens file name with the given attributes. The file will be created if it 
doesn't exist. Returns 1 if successful, otherwise. 

long Position () const; 

Returns the current position of the file pointer. Returns -1 to indicate an 
error. 

int Read( void *buffer, int numBytes ); 

Reads numBytes from the file into buffer. 

long Read( void huge *buffer, long numBytes ); 

Reads numBytes from the file into buffer (32-bit Windows version). 

static void Remove ( const char *name ); 

Removes file name. Returns if successful, -1 if unsuccessful. 

static void Rename( const char *oldName, const char *newName ); 

Renames file oldName to newName. 

long Seek( long offset, int origin = beg ); 

Repositions the file pointer to offset bytes from the specified origin. 

long SeekToBegin ( ) ; 

Repositions the file pointer to the beginning of the file. 

long SeekToEnd () ; 

Repositions the file pointer to the end of the file. 

static int SetStatus ( const char *name, const TFileStatusk status ); 

Sets file name's status to status. 

void UnlockRange (long Position, uint32 count ); 

Unlocks the range at the given Position. 

See also: LockRange 

int Write ( const void *buffer, int numBytes ; ); 
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Writes numbytes of buffer to the file. 

long Write ( const void huge *buffer, long numBytes ); 
Writes numbytes of buffer to the file (32-bit Windows version). 



String class 



cstring.h 



class string 

This class uses a technique called "copy-on-write." Multiple instances of a 
string can refer to the same piece of data so long as it is in a "read-only" 
situation. If a string writes to the data, a copy is automatically made if more 
than one string is referring to it. 



StripType 



Type definitions 



enum StripType { Leading, Trailing, Both }; 

Enumerates type of stripping. See strip in the "Public member functions' 
section for this class. 



Public constructors and destructor 



Constructor 



Constructor 



Constructor 



Constructor 



Constructor 



Constructor 



string!); 

The default constructor. Creates a string of length zero. 

string (const string _FAR &s); 

Copy constructor. Creates a string that contains a copy of the contents of 
string s. 

string( const string _FAR &s, size_t n ) 

Creates a string containing a copy of the n bytes of string s. 

string(const char _FAR *cp) ; 

Creates a string containing a copy of the bytes from the location pointed to 
by cp through the first byte (conversion from char*). 

string(const char _FAR *cp, size_t n) ; 

Creates a string containing a copy of the n bytes beginning at the location 
pointed to by cp. 

string ( char c ) 
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Constructs a string containing the character c. 
Constructor string ( char c, size_t n ) 

Constructs a string containing the character c repeated n times. 
Constructor string ( signed char c ) 

Constructs a string containing the character c. 
Constructor string ( signed char c, size_t n ) 

Constructs a string containing the character c repeated n times. 
Constructor string ( unsigned char c ) 

Constructs a string containing the character c. 
Constructor string( unsigned char c, size_t n ) 

Constructs a string containing the character c repeated n times. 
Constructor string (const TSubString _FAR &ss); 

Constructs a string from the substring ss. 

Constructor string ( const char _far *cp ) 

stringf const char far *cp, size_t n ) 

Constructs strings for Windows small and medium memory models. 
Constructor stringf HINSTANCE instance, UINT id, int len = 255 ) 

Windows version for constructing a string from a resource. 
Destructor -StringO; 

Destroys the string and frees all resources allocated to this object. 

Public member functions 

ansi_tO_oem void ansi_to_oem() 

Converts the target string from the ANSI character set into the OEM- 
defined character set (Windows only). 

append string _FAR & append ( const string _FAR &s ) 

Appends string s to the target string. 

string _FAR & append ( const string _FAR &s, size_t n ) 

Appends the first n characters of string s to the target string. 

string _FAR & append ( const char _FAR *cp, size_t n ) 
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assign 



compare 



contains 



copy 



c str 



Appends the first n characters of the character array cp to the target string. 

string _FAR & assign ( const string _FAR &s ) ; 

Assigns string s to target string. 

See also: operator = 

string _FAR & assign ( const string _FAR &s, size_t n ); 

Assigns n characters of string s to target string. 

See also: operator = 

int compare (const string _FAR &s); 

Compares the target string to the string s. compare returns an integer less 
than, equal to, or greater than 0, depending on whether the target string is 
less than, equal to, or greater than s. 

int compare (const string _FAR &s, size_t n ); 

Compares not more than n characters from the target string to the string s. 

int contains (const char _FAR * pat) const 

Returns 1 if pat is found in the target string, otherwise. 

int contains (const string _FAR & s) const 

Returns 1 if string s is found in the target string, otherwise. 

size_t copy( char _FAR *cb, size_t n ) 

Copies at most n characters from the target string into the char array 
pointed to by cb. copy returns the number of characters copied. 

size_t copy( char _FAR *cb, size_t n, size_t pos ) 

Copies at most n characters beginning at position pos from the target string 
into the char array pointed to by cb. copy returns the number of characters 
copied. 

string copyO const throw ( xalloc ). 

Returns a distinct copy of the string. 

const char _FAR *c_str() const 

Returns a pointer to a zero-terminated character array that holds the same 
characters contained in the string. The returned pointer might point to the 
actual contents of the string, or it might point to an array that the string 
allocates for this function call. The effects of any direct modification to the 
contents of this array are undefined, and the results of accessing this array 
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after the execution of any non-const member function on the target string 
are undefined. 

Conversions from a string object to a char* are inherently dangerous, 
because they violate the class boundary and can lead to dangling pointers. 
For this reason class string does not have an implicit conversion to char*, 
but provides c_str for use when this conversion is needed. 

find size_t find( const string _FAR &s ) 

Locates the first occurrence of the string s in the target string. If the string is 
found, it returns the position of the beginning of s within the target string. 
If the string s is not found, it returns NPOS. 

size_t find( const string _FAR &s, size_t pos ) 

Locates the first occurrence of the string s in the target string, beginning at 
the position pos. If the string is found, it returns the position of the 
beginning of s within the target string. If the s is not found, it returns NPOS 
and does not change pos. 

size_t find( const TRegexp _FAR &pat, size_t i = ) 

Searches the string for patterns matching regular expression pat beginning 
at location i. It returns the position of the beginning of pat within the target 
string. If the pat is not found, it returns NPOS and does not change pos. 

size_t find( const TRegexp _FAR &pat, size_t _FAR *ext, size_t i = ■) 
const; 

Searches the string for patterns matching regular expression pat beginning 
at location i. Parameter ext returns the length of the matching string if 
found. It returns the position of the beginning of pat within the target 
string. If the pat is not found, it returns NPOS and does not change pos. 

See also: rfind 

find_first_of size_t find_first_of ( const string _FAR &s ) const 

Locates the first occurrence in the target string of any character contained 
in string s. If the search is successful find_first_of returns the character 
location. If the search fails or if pos > length ( ) , find_first_of returns 0. 

size_t find_first_of ( const string _FAR &s, size_t pos ) const < 

Locates the first occurrence in the target string of any character contained 
in string s. If the search is successful, pos is set to the position of that 
character within the target string, and find_jirst_of returns 1. If the search 
fails or if pos > length [) , find_first_of returns 0. 

find_first_not_of size_t find_first_not_of ( const string _FAR &s) const 
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Locates the first occurrence in the target string of any character not 
contained in string s. If the search is successful, find_first_not_of returns the 
character location. If the search fails or if pos > length ( ) , find_first_not_of 
returns 0. 

size_t f ind_f irst_not_of ( const string _FAR &s ; size_t pos ) const 
Locates the first occurrence in the target string of any character not 
contained in string s. If the search is successful, pos is set to the position of 
that character within the target string, and find_first_not_of returns 1. If the 
search fails or if pos > length ( ) , find_first_not_of returns 0. 

find_last_of size_t f ind_last_of ( const string _FAR &s ) const 

Locates the last occurrence in the target string of any character contained in 
string s. If the search is successful findJast_of returns the character location. 
If the search fails or if pos > length ( ) , find_last_of returns 0. 

size_t find_last_of ( const string _FAR &s, size_t pos ) const 

Locates the last occurrence in the target string of any character contained in 
string s. If the search is successful,pos is set to the position of that character 
within the target string, and find_last_of returns 1. If the search fails or if pos 
> length ( ) , find_last_of returns 0. 

find_lastjlOt_of , size_t f ind_last_not_of ( const string _FAR &s ) const 

Locates the last occurrence in the target string of any character not 
contained in string s. If the search is successful find_last_not_of returns the 
character location. If the search fails or if pos > length ( ) , find_last_not_of 
returns 0. 

size_t f ind_last_not_of ( const string _FAR &s, size_t pos ) const 

Locates the last occurrence in the target string of any character not 
contained in string s. If the search is successful, pos is set to the position of 
that character within the target string, and find_last_not_of returns 1. If the 
search fails or if pos > length ( ) , find_last_not_of returns 0. 

9&t_at c h ar get_at( size_t pos ) const throw( outofrange ); 

Returns the character at the specified position. If pos > length ( ) -1, an 
outofrange exception is thrown. 

See also: put_at 
get_case_sensitive_flag static int get_case_sensitiveFlag() 

Returns if string comparisons are case sensitive, 1 if not. 
get_mitial_capacity static unsigned get_initial_capacity() 

Returns the number of characters that will fit in the string without resizing. 
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get_max_waste static unsigned get_max_waste() 

After a string is resized, returns the amount of free space available. 
get_paranoid_check static int get_paranoid_check ( ) ; 

Returns 1 if paranoid checking is enabled, if not. 
get_resize_increment static unsigned get_resize_increment ( ) 

Returns the string resizing increment. 
get_skipwhitespace_flag static int get_skipwhitespace_f lag ( ) 

Returns 1 if whitespace is skipped, if not. 
hash unsigned hash() const; 

Returns a hash value. 
initial_capacity static size_t initial_capacity(size_t ic = 63); 

Sets initial string allocation capacity. 

insert string _FAR &insert ( size_t pos, const string _FAR &s ) 

Inserts string s at position pos in the target string, insert returns a reference 
to the resulting string. 

string _FAR &insert( size_t pos, const string _FAR &s, size_t n ) 

Inserts n characters of string s at position pos in the target string, insert 
returns a reference to the resulting string. 



is null 



length 



max waste 



oem to ansi 



prepend 



int is_null() const 

Returns 1 if the string is empty, otherwise. 

unsigned length () const 

Returns the number of characters in the target string. Since null characters 
can be stored in a string, length ( ) might be greater than strlen ( c_str ( ) ) . 

static size_t MaxWaste(size_t mw = 63); 

Sets the maximum empty space size and resizes the string. 

void oem_to_ansi() 

Windows function for converting the target string from the ANSI character 
set to the OEM-defined character set (Windows only). 

string _FAR &prepend( const string _FAR &s ) 

Prepends string s to the target string. 
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string _FAR &prepend( const string _FAR &s, size_t n ) 

Prepends the first n characters of string s to the target string. 

string _FAR &prepend( const char _FAR *cp ) 

Prepends the character array cp to the target string. 

string _FAR &prepend( const char _FAR *cp, size_t n ) 

Prepends the first n characters of the character array cp to the target string. 

put_at void put_at( size_t pos, char c ) throw( outofrange ) ; 

Replaces the character at pos with c. If pos == length ( ) , put At appends c to 
the target string. If pos > length ( ) an outofrange exception is thrown. 

readjile istream _FAR &read_file( istream _FAR &is) ; 

Reads from input stream is until an EOF or a null terminator is reached. 
readjine istream _FAR &read_line (istream _FAR &is); 

Reads from input stream is until an EOF or a newline is reached. 
read_String istream _FAR &read_string( istream _FAR &is); 

Reads from input stream is until an EOF or a null terminator is reached. 
read_tO_delim istream _FAR &read_to_delim( istream _FAR &is, char delim='\n'); 

Reads from input stream is until an EOF or a delim is reached. 

read_token istream _FAR &read_token( istream _FAR &is); 

Reads from input stream is until whitespace is reached. Note that this 
function skips any initial whitespace. 

rf' n d size_t rfind( const string _FAR &s ) 

Locates the last occurrence of the string s in the target string. If the string is 
found, it returns the position of the beginning of the string s within the 
target string. If s is not found, it returns NPOS. 

size_t rfind( const string _FAR &s, size_t pos ) 

Locates the last occurrence of the string s that is not beyond the position pos 
in the target string. If the string is found, it returns the position of the 
beginning of s within the target string. If s is not found, it returns NPOS 
and does not change pos. 

See also: find 

remove string _FAR &remove( size_t pos ); 
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replace 



reserve 



resize 



Removes the characters from pos to the end of the target string and returns 
a reference to the resulting string. 

string _FAR &remove( size_t pos, size_t n ) 

Removes at most n characters from the target string beginning at pos and 
returns a reference to the resulting string. 

string _FAR &replace( size_t pos, size_t n, const string _FAR &s ) 

Removes at most n characters from the target string beginning at pos, and 
replaces them with a copy of the string s. replace returns a reference to the 
resulting string. 

string _FAR &replace( size_t pos', size_t nl, const string _FAR &s, size_t 
n2 ) 

Removes at most nl characters from the target string beginning at pos, and 
replaces them with the first nl characters of string s. replace returns a 
reference to the resulting string. 

size_t reserved const 

Returns an implementation-dependent value that indicates the current 
internal storage size. The returned value is always greater than or equal to 

length(). 

void reserve ( size_t ic ) 

Suggests to the implementation that the target string might eventually 
require ic bytes of storage. 



resize increment 



set case sensitive 



void resize(size_t m) ; 

Resizes the string to m characters, truncating or adding blanks as necessary. 

static size_t resize_increment(size_t ri = 64); 

Sets the resize increment for automatic resizing. 

static int set_case_sensitive(int tf = 1)'; 

Sets case sensitivity. 1 is case sensitive; is not case sensitive. 

set_paranoid_Check static int set_paranoid_check(int ck = 1); 

String searches use a hash value scheme to find the strings. There is a 
possibility that more than one string could hash to the same value. Calling 
set_paranoid_check with ck set to 1 forces checking the string found against 
the desired string with the C library function strcmp. When 
set_paranoid_check is called with ck set to 0, this final check isn't made. 



skip_whitespace 



static int skip_whitespace(int sk = 1); 
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strip 



substr 



substring 



to lower 



to_upper 



Set to 1 to skip whitespace after a token read, otherwise. 

TSubString strip ( StripType s = Trailing, char c=' ' ) ; 

Strips away c characters from the beginning, end, or both (beginning and 
end) of string s, depending on StripType. 

string substr ( size_t pos ) const 

Creates a string containing a copy of the characters from pos to the end of 
the target string. 

string substr ( size_t pos, size_t n ) const 

Creates a string containing a copy of not more than n characters from pos to 
the end of the target string. 

TSubString substring ( const char _FAR *cp ) 

Creates a TSubString object containing a copy of the characters pointed to 
by *cp. 

const TSubString substring ( const char _FAR *cp ) const 

Creates a TSubString object containing a copy of the characters pointed to 
by *cp. 

TSubString substring ( const char _FAR *cp, size_t start ) 

Creates a TSubString object containing a copy of the characters pointed to 
by *cp, starting at character start. 

const TSubString substring ( const char _FAR *cp, size_t start ) const 

Creates a TSubString object containing a copy of the characters pointed to 
by *cp, starting at character start. 

void to_lower ( ) ; 

Changes the string to lowercase. 

void to_upper() ; 

Changes target string to uppercase. 



Protected member functions 



assert element 



assert index 



void assert_element( size_t pos ) const 

Throws an outofrange exception if an invalid element is given. 

void assert_index( size_t pos ) const 
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cow 



valid element 



valid index 



Throws an outofrange exception if an invalid index is given. 

void cow() ; 

Copy on write. Multiple instances of a string can refer to the same piece of 
data as long as it is in a read-only situation. If a string writes to the data, 
then cow (copy on write) is called to make a copy if more than one string is 
referring to it. 

int valid_element ( size_t pos ) const 

Returns 1 if pos is an element of the string, otherwise. 

int valid_index( size_t pos ) const 

Returns 1 if pos is a valid index of the string, otherwise. 



Operators 



Operator = 



Operator += 



Operator + 



Operator [] 



Operator () 



string _FAR & operator^" (const string _FAR &s); 

If the target string is the same object as the parameter passed to the 
assignment, the assignment operator does nothing. Otherwise it performs 
any actions necessary to free up resources allocated to the target string, 
then copies s into the target string. 

string _FAR & operator += (const String _FAR &s) 

Appends the contents of the string s to the target string. 

string _FAR & operator+= (const char _FAR *cp) ; 

Appends the contents of cp to the target string. 

friend String _Cdecl _FARFUNC operator+ (const String _FAR &, const char 
_FAR *cp); 

Concatenates string s and cp. 

char _FAR & operator[] (size_t pos); 

Returns a reference to the character at position pos. 

char operator [] (size_t pos) const; 

Returns the character at position pos. 

char _FAR & operator () (size_t pos); 

Returns a reference to the character at position pos. 

TSubString operator () (size_t start, size_t len) ; 
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Operator == 



Operator != 



Returns the substring beginning at location start and spanning len bytes. 

TSubString operator!) (const TRegexp _FAR & re) ; 

Returns the first occurrence of a substring matching regular expression re. 

TSubString operator!) (const TRegexp _FAR & re, size_t start); 

Returns the first occurrence of a substring matching regular expression re, 
beginning at location start. 

char operator () (size_t pos) const; 

Returns the character at position pos. 

const TSubString operator () (size_t start, size_t len) const; 

Returns the substring beginning at location start and spanning len bytes. 

const TSubString operator () (const TRegexp _FAR & pat) const; 

Returns the first occurrence of a substring matching regular expression re. 

const TSubString operator () (const TRegexp _FAR & pat, size_t start) const; 

Returns the first occurrence of a substring matching regular expression re, 
beginning at location start. 

friend int operator == ( const String _FAR &sl, const String _FAR &s2 ) ; 

Tests for equality of string si and string s2. Two strings are equal if they 
have the same length, and if the same location in each string contains 
characters that compare equally. Operator == returns a 1 to indicate that the 
strings are equal, and a to indicate that they are not equal. 

friend int operator == ( const String _FAR &s, const char _FAR *cp ) ; 
friend int operator == ( const char _FAR *cp, const String _FAR &s ) ; 

Tests for equality of string si and char *cp. The two are equal if they have 
the same length, and if the same location in each string contains characters 
that compare equally. Operator == returns a 1 to indicate that the strings 
are equal, and a to indicate that they are not equal. 

friend, int operator != ( const String _FAR &sl, const String _FAR &s2 ); ' 

Tests for inequality of strings si and s2. Two strings are equal if they have 
the same length, and if the same location in each string contains characters 
that compare equally. Operator != returns a 1 to indicate that the strings are 
not equal, and a to indicate that they are equal. 

friend int operator != ( const String _FAR &s, const char _FAR *cp ); 
friend int operator != ( const char _FAR *cp, const String _FAR &s ); 



502 



Library Reference 



String class 



Operator < 



Operator <= 



Operator > 



Operator >= 



Operator » 



Tests for inequality between string s and char *cp. The two are equal if they 
have the same length, and if the same location in each string contains the 
same character. Operator != returns a 1 to indicate that the strings are not 
equal, and a to indicate that they are equal. 

friend int operator < ( const String _FAR &sl, const String _FAR &s2 ); 

Compares string si to string s2. Returns 1 if string si is less than s2, 
otherwise. 

friend int operator < ( const String _FAR &s, const char _FAR *cp); 
friend int operator < ( const char _FAR *cp, const String _FAR &s ) ; 

Compares string si to *cp2. Returns 1 if the left side of the expression is less 
than the right side, otherwise. 

friend int operator <= ( const String _FAR &sl, const String _FAR &s2 ); 

Compares string si to string s2. Returns 1 if string si is less than or equal to 
s2, otherwise. 

friend int operator <= ( const String _FAR &s, const char _FAR *cp ); 
friend int operator <= ( const char _FAR *cp, const String _FAR &s ) ; 

Compares string si to *cp. Returns 1 if the left side of the expression is less 
than or equal to the right side, otherwise. 

friend int operator > ( const String _FAR &sl, const String _FAR &s2 ); 

Compares string si to string s2. Returns 1 if string si is greater than s2, 
otherwise. 

friend int. operator > ( const String _FAR &s ; const char _FAR *cp ); 
friend int operator > ( const char _FAR *cp, const String _FAR &s ) ; 

Compares string si to *cp2. Returns 1 if the left side of the expression is 
greater than the right side, otherwise. 

friend int operator >= ( const String _FAR &sl, const String _FR &s2 ); 

Compares string si to string s2. Returns 1 if string si is greater than or 
equal to s2, otherwise. 

friend int operator >= ( const String _FAR &s, const char _FAR *cp ); 
friend int operator >= ( const char _FAR *cp, const String _FAR &s ) ; 

Compares string si to *cp. Returns 1 if the left side of the expression is 
greater than or equal to the right side, otherwise. 

friend ipstream _FAR & operator » ( ipstream _FAR & is, string _FAR & str ) ; 
Extracts string str from input stream is. 
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String class 



Related global operators and functions 



Operator » 



Operator « 



Operator + 



getline 



to lower 



to_upper 



istream _FAR & _Cdecl _FARFUNC operator»(istream _FAR &is, string _FAR 
&s); > 

Behaves the same as operator» (istream&, char *)' (see Chapter 5), and 
returns a reference to is. 

ostream _FAR & _Cdecl _FARFUNC operator«(ostream _FAR &os, const String 
_FAR & s); . 

Behaves the same as operator« (ostream&, const char * ) (see Chapter 5) 
except that it does not terminate when it encounters a null character in the 
string. Returns a reference to os.' 

opstream _FAR& _Cdecl operator « ( opstream _FAR & os, const string _FAR 
& str ) ; 

Inserts string str into persistent output stream os. 

string _Cdecl _FARFUNC operator + ( const char _FAR *cp, const string _FAR 
& s); 

Concatenates *cp and string s. 

string _Cdecl _FARFUNC operator + ( const string _FAR &sl, const string 
_FAR &s2 ) ; 

Concatenates string si and s2. 

istream _FAR & _Cdecl getline ( istream _FAR &is, string _FAR &s ); 

Behaves the same as istream: :getline (chptr, NPOS), except that instead of 
storing into a char array, it stores into a string, getline returns a reference to 
is. 

istream _FAR & _Cdecl getline ( istream _FAR &is, string _FAR &s, Char c ); 

Behaves the same as istream: :getline (cb, NPOS, c), except that instead of 
storing into a char array, it stores into a string, getline returns a reference to 
is. 

String _Cdecl _FARFUNC to_lower (const string _FAR &s) ; 

Changes string s to uppercase. 

String _Cdecl _FARFUNC to_upper (const string _FAR &s);- 

Changes string s to lowercase. 
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TSubString class 



TSubString class 



cstring.h 



get_at 



isjiull 
length 
put_at 

start 

tojower 

to_upper 



assert element 



class TSubString 

Addresses selected substrings. 

Public member functions 



char get_at( size_t pos ) const 

Returns the character at the specified position. If pos > length ( ) -1, an 
exception is thrown. 

See also: put_at 

int is_null() const 

Returns 1 if the string is empty, otherwise. 

size_t length () . const 
Returns the substring length. 

void put_at( size_t pos, char c ) 

Replaces the character at pos with c. If pos == length ( ) , put At appends c to 
the target string. If pos > length ( ) , an exception is thrown. 

int start () const 

Returns the index of the starting character. 

void to_lower(); 

Changes the substring to lowercase. 

void to_upper ( ) ; 

Changes the substring to uppercase. 



Protected member functions 



int assert_element(size_t pos) const; 

Returns 1 if pos represents a valid index into the substring, otherwise. 



Operators 



Operator = 



TSubString _FAR & operator= (const string _FAR &s); 
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TSubString class 



Operator == 



Operator != 



Operator () 



Operator [] 



Operator ! 



Copies s into the target substring. 

int operator== (const char _FAR * cp) const; 

Tests for equality between the target substring and *cp. The two are equal if 
they have the same length, and if the same location in each string contains 
the same character. Operator == returns a 1 to indicate that the strings are 
equal, and a to indicate that they are not equal. 

int operator— (const string _FAR & s) const; 

Tests for equality between the target substring and string s. Two are equal 
if they have the same length, and if the same location in each string 
contains the same character. Operator == returns a 1 to indicate that the 
strings are equal, and a to indicate that they are not equal. 

int operator! = (const char _FAR * cp) const 

Tests for inequality between the target string and *cp. Two strings are equal 
if they have the same length/and if the same location in each string 
contains the same character. Operator != returns a 1 to indicate that the 
strings are not equal, and a to indicate that they are equal. 

int operator != (const string _FAR &' s) const; 

Tests for inequality between the target string and string s. Two strings are 
equal if they have the same length, and if the same location in each string 
contains the same character. Operator != returns a 1 to indicate that the 
strings are not equal, and a to indicate that they are equal. 

char _FAR & operator () (si ze_t pos); 

Returns a reference to the character at position pos. 

char operator () (size_t pos) const; 

Returns the character at position pos. 

char _FAR& operator [] (size_t pos); 

Returns a reference to the character at position pos. 

char operator [] (size_t pos) const; 

Returns the character at position pos. 

int operator! () const 

Detects null substrings. Returns 1 if the substring is not null. 
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TCriticalSection class 



TCriticalSection class thread.h 

class TCriticalSection 

TCriticalSection provides a system-independent interface to critical sections 
in threads. TCriticalSection objects can be used in conjunction with 
TCriticalSection: :Lock objects to guarantee that only one thread can be 
executing any of the code sections protected by the lock at any given time. 

See also: TCriticalSection: :Lock 

Constructors and destructor 

Constructor TCriticalSection (); 

Constructs a TCriticalSection object. 
Destructor ~TCriticalSection(); 

Destroys a TCriticalSection object. 

TCriticalSection::Lock class thread.h 

class Lock 

This nested class handles locking and unlocking critical sections. Here's an 
example: 

TCriticalSection LockF; 

void f() '• - 

{ 

TCriticalSection: : Lock (LockF) ; 

// critical processing here 
} 

Only one thread of execution will be allowed to execute the critical code 
inside function / at any one time. 

Public constructors and destructor 

Constructor Loc k( const TCriticalSectionk ); 

Requests a lock on the TCriticalSection object. If no Lock object in another 
thread holds a lock on that TCriticalSection object, the lock is allowed and 
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TCriticalSection::Lock class 



Destructor 



execution continues. If a Lock object in another thread holds a lock on that 
object, the requesting thread is blocked until the lock is released. 

-Lock ( ) ; 

Releases the lock. 



TMutex class 



thread.h 



TMutex provides a system-independent interface to critical sections in 
threads. TMutex objects can be used in conjunction with TMutex::Lock 
objects to guarantee that only one thread can be executing any of the code 
sections protected by the lock at any given time. 

The differences between the classes TCriticalSection and TMutex are that a 
timeout can be specified when creating a Lock on a TMutex object, and that 
a TMutex object has a HANDLE that can be used outside the class. This 
mirrors the distinction made in Windows NT between a 
CRITICALSECTION and a Mutex. Under NT a TCriticalSection object is 
much faster than a TMutex object. Under operating systems that don't make 
this distinction a TCriticalSection object can use the same underlying 
implementation as a TMutex, losing the speed advantage that it has under 
NT. 

Public constructors and destructor 



Constructor 



Destructor 



TMutex () ; 

Constructs a TMutex object. 

-TMutex (); 

Destroys a TMutex object. 



HANDLE 



Operators 



operator HANDLE () const; 

Returns the handle of the underlying Windows NT semaphore object. 



TMutex::Lock class 



thread.h 



This nested class handles locking and unlocking TMutex objects. 
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TMutex::Lock class 



Public constructors 



Constructor Lock( const TMutexk, unsigned long timeOut = NoLimit ); 

Requests a lock on the TMutex object. If no Lock object in another thread 
holds a lock on that TMutex object, the lock is allowed and execution 
continues. If a Lock object in another thread holds a lock on that object, the 
requesting thread is blocked until the lock is released. 

Public member functions 



Release 



void Released ; 

Releases the lock on the TMutex object. 



TSync class 



thread.h 



TSync provides a system-independent interface for building classes that act 
like monitors — classes in which only one member function can execute on a 
particular instance at any one time. TSync uses TCriticalSection, has no 
public members, and can only be used as a base class. Here is an example 
of TSync in use: 

class ThreadSafe : private TSync 

{ 

public: 

void f ( ) ; 

void g ( ) ; 
private: 

int i; 

void ThreadSafe: :f() 
{. 

Lock (this); 

if ( i == 2 ) 

i = 3; 
} 

void ThreadSafe ::g() 
{ 

Lock(this); - 

if ( i == 3 ) 
'i i = 2; 
} 
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TSync class 



See also: class TSyncr.Lock 



Constructor 



Constructor 



Protected constructors 



TSync (); 

Default constructor. 

TSync ( const TSynck ) ; 

Copy constructor. Does not copy the TCriticalSection object. 



Operator = 



Protected operators 



const TSync& operator = ( const TSync& s ) 

Assigns s to the target, and does not copy the TCriticalSection object. 



TSync:: Lock class 



thread.h 



class Lock : private TCriticalSection: :Lock 

This nested class handles locking and unlocking critical sections. 

Public constructors and destructor 



Constructor 



Destructor 



Lock( const TSync *s ) ; 

Requests a lock on the critical section of the TSync object pointed to by s. If 
no other Lock object holds a lock on that TCriticalSection object, the lock is 
allowed and execution continues. If another Lock object holds a lock on that 
object, the requesting thread is blocked until the lock is released. 

-Lock ( ) ; 

Releases the lock. 



TThread class 



thread.h 



class TThread 

TThread provides a system-independent interface to threads. Here is an 
example: 
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TThread class 



class TimerThread : private TThread 

{ 

public: 

TimerThread ( ) : Count (0) {} 
private: 

unsigned long Run(); 

int Count; 
}; 

unsigned long TimerThread: : Run () 
{ 

// loop 10 times 

while ( Count++ < 10 ) 

{ 

Sleep (1000); // delay 1 second 
cout « "Iteration " « Count « endl; 

} 

return 0L; 
} 

int main() 

{■ 

TimerThread timer; 

timer. Start () ; 

Sleep( 20000 ); // delay 20 seconds 

return 0; 
} 



Type definitions 



Status enum status { Created, Running, Suspended, Finished, Invalid }; 

Describes the state of the thread, as follows: 

■ Created. The object has been created but its thread has not been started. 
The only valid transition from this state is to Running, which happens on 
a call to Start. In particular, a call to Suspend or Resume when the object is 
in this state is an error and will throw an exception. 

■ Running. The thread has been started successfully. There are two 
transitions from this state: 

• When the user calls Suspend, the object moves into the Suspended state. 

• When the thread exits, the object moves into the Finished state. 

Calling Resume on an object that is in the Running state is an error and 
will throw an exception. 
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TThread class 



Constructor 
Constructor 
Destructor 



■ Suspended. The thread has been suspended by the user. Subsequent calls 
to Suspend nest, so there must be as many calls to Resume as there were to 
Suspend before the thread resumes execution/ 

■ Finished. The thread has finished executing. There are no valid transitions 
out of this state. This is the only state from which it is legal to invoke the 
destructor for the object. Invoking the destructor when the object is in 
any other state is an error and will throw an exception. 

Protected constructors and destructor 

TThread ( ) ; 

Constructs an object of type TThread. 

TThread ( const TThread& ); 

Copy constructor. Puts the target object into the Created state. 

virtual -TThread ( ) ; 

Destroys the TThread object. 



Public member functions 



GetPriority 



GetStatus 



Resume 



SetPriority 



Start 



Suspend 



int GetPriority () const; 
Gets the thread priority. 
See also: SetPriority 

Status GetStatus () const; 

Returns the current status of the thread. See data member Status for 
possible values. 

unsigned long ResumeO; 

Resumes execution of a suspended thread. 

int SetPriority ( int ) ; 

Sets the thread priority. 

See also: GetPriority 

HANDLE Start (); ' 

Begins execution of the thread, and returns the thread handle. 

unsigned long Suspend!); 
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TThread class 



Terminate 



TerminateAndWait 



WaitForExit 



Suspends execution of the thread. 

void Terminated ; 

Sets an internal flag that indicates that the thread should exit. The derived 
class can check the state of this flag by calling ShouldTerminate. 

void TerminateAndWait ( unsigned long timeout = (unsigned long) (-1) ); 

Combines the behavior of Terminate and WaitForExit. Sets an internal flag 
that indicates that the thread should exit and blocks the calling thread until 
the internal thread exits or until the time specified by timeout, in 
milliseconds, expires. A timeout of -1 says to wait indefinitely. 

void WaitForExit ( unsigned long timeout = (unsigned long) (-1) ); 

Blocks the calling thread until the internal thread exits or until the time 
specified by timeout, in milliseconds, expires. A timeout of -1 says wait 
indefinitely. 

Protected member functions 



ShouldTerminate 



int ShouldTerminate ( ) const; 

Returns a nonzero value to indicate that Terminate or TerminateAndWait has 
been called and that the thread will finish its processing and exit. 



Protected operators 



Operator = 



const TThread& operator = ( const TThreadk ) ; 

The TThread assignment operator. The target object must be in either the 
Created or Finished state. If so, assignment puts the target object into the 
Created state. If the object is not in either state an exception will be thrown. 



TThread: :TThreadError class 



thread.h 



class TThreadError 

TThreadError defines the exceptions that are thrown when a threading error 
occurs. 
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TThread::TThreadError class 



Type definitions 



ErrorType 



enum ErrorType 
.{ 

SuspendBeforeRun, 
ResumeBeforeRun, 
ResumeDuringRun, 
SuspendAf terExit , 
ResumeAfterExit, 
CreationFailure, 
DestroyBef oreExit , 
AssignError 

Identifies the type of error that occurred. The following list explains each 
error type: 

■ SuspendBeforeRun. The user called Suspend on an object before calling 
Start. 

m ResumeBeforeRun. The user called Resume on an object before calling Start. 

■ ResumeDuringRun. The user called Resume on a thread that was not 
suspended. 

■ SuspendAf terExit. The user called Suspend on an object whose thread had 
already exited. 

■ ResumeAfterExit. The user called Resume on an object whose thread had 
already exited. 

■ CreationFailure. The operating system was unable to create the thread. 

■ DestroyBef oreExit. The object's destructor was invoked before its thread 
had exited. 

■ AssignError. An attempt was made to assign to an object that was not in 
either the Created or Finished state. 

Public member functions 



GetElTOrType ErrorType GetErrorType ( ) const; 

Returns the ErrorType for the error that occurred. 
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TTime type definitions 



TTime type definitions 



time.h 



typedef unsigned HourTy; 
typedef unsigned MinuteTy; 
typedef unsigned SecondTy; 
typedef unsigned long ClockTy; 

Type definitions for hours, minutes, seconds, and seconds since January 1, 
1901. 



TTime class 



time.h 



Constructor 



Constructor 



Constructor 



Constructor 



AsString 

BeginDST 

Between 



class TTime 

Class TTime encapsulates time functions and characteristics. 

Public constructors 

TTime ( ) ; 

Constructs a TTime object with the current time. 

TTime ( ClockTy s ) ; 

Constructs a TTime object with the given s (seconds since January 1, 1901). 

TTime ( HourTy h, MinuteTy m, SecondTy s = ); 
Constructs a TTime object with the given time and today's date. 
TTime( const TDate&, HourTy h=0, MinuteTy m=0, SecondTy s=0 ); 
Constructs a TTime object with the given time and date. 

Public member functions 

string AsString () const; 

Returns a string object containing the time. 

static TTime BeginDST ( unsigned year ); 

Returns the start of daylight savings time for the given year. 

int Between! const TTime& a, const TTimek b ) const; 

Returns 1 if the target date is between TTimes a and b, otherwise. 
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TTime class 



CompareTo 



EndDST 



Hash 



Hour 



HourGMT 



IsDST 



IsValid 



Max 



Min 



Minute 



MinuteGMT 



PrintDate 



Second 



Seconds 



int CompareTo ( const TTime & ) const; 

Compares t to this TTime object and returns if the times are equal, 1 if t is 
earlier, and -1 if t is later. 

static TTime EndDST (unsigned year ); 

Returns the time when daylight savings time ends for the given year. 

unsigned Hash() const; 

Returns seconds since January 1, 1901. 

Hourly Hour() const; 

Returns the hour in local time. 

HourTy HourGMT () const; 

Returns the hour in Greenwich Mean Time. 

int IsDST () const; 

Returns 1 if the time is in daylight savings time, otherwise. 

int IsValid () const; 

Returns 1 if this TTime object contains a valid time, otherwise. 

TTime Max( const TTime& t ) const; 

Returns either this TTime object or t, whichever is greater. 

TTime Min( const TTime& t ) const; 

Returns either this TTime object or t, whichever is lesser. 

MinuteTy Minuted const; 

Returns the minute in local time. 

MinuteTy MinuteGMT () const; 

Returns the minute in Greenwich Mean Time. 

static int PrintDate ( int flag); 

Set flag to 1 to print the date along with the time; set to to not print the 
date. Returns the old setting. 

SecondTy Second () const; 

Returns seconds. 

ClockTy Seconds () const; 
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TTime class 



AssertDate 



RefDate 



MaxDate 



Operator < 
Operator <= 
Operator > 
Operator >= 
Operator == 
Operator != 
Operator ++ 
Operator - - 



Returns seconds since January 1, 1901. 



Protected member functions 



static int AssertDate ( const TDate& d ); 

Returns 1 if d is between the earliest valid date {RefDate) and the latest valid 
date {MaxDate). 



Protected data members 



static const TDate RefDate; 

The minimum valid date for TTime objects: January 1, 1901. 

static const TDate MaxDate; 

The maximum valid date for TTime objects. 



Operators 



int operator < ( const TTime& t ) const; 

Returns 1 if the target time is less than time t, otherwise. 

int operator <= ( const TTimek t ) const; 

Returns 1 if the target time is less than or equal to time t, otherwise. 

int operator > ( const TTimek t ) const; 

Returns 1 if the target time is greater than time t, otherwise. 

int operator >= ( const TTime& t ) const;' 

Returns 1 if the target time is greater than or equal to time t, otherwise. 

int operator == ( const TTimek t ) const; 

Returns 1 if the target time is equal to time t, otherwise. 

int operator != ( const TTimek t ) const; 

Returns 1 if the target time is not equal to time t, otherwise. 

void operator++() ; • 

Increments time by 1 second. 

void operator-- () ; 
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TTime class 



Operator += 
Operator -= 
Operator + 

Operator - 

Operator « 



Operator » 



Decrements time by 1 second. 

void operator+=(long s); 

Adds s seconds to the time. 

void operator-=(long s); 

Subtracts s seconds from the time. 

friend. TTime operator + ( const TTime& t, long s ); 
friend TTime operator + ( long s, const TTime& t ); 

Adds s seconds to time t . 

friend TTime operator - ( const TTime& t, long s ); 
friend TTime operator - ( long s, const TTimeS t ); 

Performs subtraction, in seconds, between s and t . 

friend ostream& operator « ( ostream& os, const TTime& t); 

Inserts time t into output stream os. 

friend opstream& operator « ( opstream& s, const TTime& d 

Inserts time t into persistent stream s. 

friend ipstream& operator » ( ipstreamk s, TTime& d ); 

Extracts time t from persistent stream s. 
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Index 



TSubString operator 506 

global string operator 504 
string operator 501 
TDate operator 487 
TTime operator 518 

TDate operator 487 
TTime operator 518 

string operator 503 
TDate operator 487 
TTime operator 517 

string operator 501 
TMVectorlmp operator 446 
TSubString operator 505 
TSync operator 510 
TThread operator 513 

string operator 503 
TDate operator 487 
TTime operator 517 

string operator 502 
TDate operator 487 
TSubString operator 506 
TTime operator 517 

string operator 501 
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++ 



TBinarySearchTreelteratorlmp operator 357 
TDate operator 487 

TIBinarySearchTreelteratorlmp operator 383 
TMArrayAsVectorlterator operator 359 
TMDequeAsVectorlterator operator 386 
TMDictionaryAsHashTablelterator operator 397 
TMDoubleListlteratorlmp operator 404 
TMHashTablelteratorlmp operator 413 
TMIArrayAsVectorlterator operator 365 



TMIDictionaryAsHashTablelterator operator 
399 

TMIDoubleListlterator operator 409 
TMIHashTablelteratorlmp operator 415 
TMIListlteratorlmp operator 423 
TMIVectorlteratorlmp operator 456 
TMListlteratorlmp operator 420 
TMVectorlteratorlmp operator 447 
TTime operator 517 



+= 



string operator 501 
TDate operator 487 
TTime operator 518 

TDate operator 487 

TMDoubleListlteratorlmp operator 405 
TTime operator 517 

TDate operator 487 
TTime operator 518 



« 



global string operator 504 
TDate operator 487 
TTime operator 518 



<= 



string operator 503 
TDate operator 487 
TTime operator 517 

string operator 502 
TDate operator 487 
TMDD Association operator 369 
TMDIAssociation operator 370 
TMID Association operator 372 
TMII Association operator 373 
TSubString operator 506 
TTime operator 517 



>= 



string operator 503 
TDate operator 487 
TTime operator 517 



» 
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string operator 503 
TDate operator 488 
TTime operator 518 

[] 

string operator 501 
TArray operator 364 
TMArray As Vector operator 359 
TMIVectorlmp operator 455 
TMVectorlmp operator 446 
TSubString operator 506 

_8087 (global variable) 299 

8086 processor 

interrupt vectors 78, 81, 134 
interrupts 145, 147 

80x86 processors 
functions (list) 13 

0x11 BIOS interrupt 39, 40 

0x12 BIOS interrupt 42, 43 

0x16 BIOS interrupt 41 

0x21 DOS interrupt 146, 147 

0x23 DOS interrupt 64 

0x29 DOS system call 187 

0x33 DOS system call 122, 229 

0x44 DOS system call 148 

0x59 DOS system call 71 

0x62 DOS system call 131 

0x1 A BIOS interrupt 43 



abnormal program termination 206, 478 

abort (function) 27 

abs (complex friend function) 466 

abs (function) 27 

absolute value 

complex numbers 45, 466 
square 468 

floating-point numbers 91 

integers 27 
long 156 
access 

DOS system calls 35, 36 

memory (DMA) 39, 41 

modes, changing 50, 75,213 

program, signal types 206 
invalid 206 

read /write 50, 117 



files 28, 60, 184, 243 
permission 184 

access (function) 28 

access flags 184,243 

access permission mask 285 

acos (complex friend function) 466 

acos (function) 28 

acosl (function) 28 

Add 

TBinarySearchTreelmp member function 379 
TIBinarySearchTreelmp member function 381 
TMArray As Vector member function 356 
TMBagAs Vector member function 374 
TMCVectorlmp member function 449 
TMDictionaryAsHashTable member function 
395 

TMDoubleListlmp member function 402 
TMHashTablelmp member function 412 
TMIArrayAs Vector member function 361 
TMIBagAs Vector member function 377 
TMICVectorlmp member function 457 
TMIDictionaryAsHashTable member function 
398 

TMIDoubleListlmp member function 407 
TMIHashTablelmp member function 414 
TMIListlmp member function 421 
TMISet As Vector member function 435 
TMListlmp member function 418 
TMSetAs Vector member function 434 

AddAt 

TMArray As Vector member function 356 
TMCVectorlmp member function 449 
TMIArrayAs Vector member function 361 

AddAtHead 

TMDoubleListlmp member function 402 
TMIDoubleListlmp member function 407 

AddAtTail 

TMDoubleListlmp member function 402 
TMIDoubleListlmp member function 407 

address segment, of far pointer 108, 178 

addresses 

memory See memory 
passed to emit 85 

adjustfield, ios data member 318 

alloch (header file) 7 

alloca (function) 29 

allocate, streambuf member function 331 



520 



Library Reference 



allocation 

memory See memory 

streamable object file buffers and 336, 344 
alphabetic ASCII codes, checking for 150 
alphanumeric ASCII codes, checking for 150 
angles (complex numbers) 467 
ansi_to_oem, string member function 493 
app, ios data member 319 
append, string member function 493 
arc cosine 28 
arc sine 30 
arc tangent 31, 32 
arg (complex friend function) 467 
argc (argument to main) 19 
_argc (global variable) 299 
ARGS.EXE 20 
argument list, variable 289 

conversion specifications and 195 

routines 18 
arguments 

command-line, passing to main 19, 299, 300 
wildcards and 21 
argv (argument to main) 19 
_argv (global variable) 300 
arrays 

of character, attribute information 300 

searching 44, 157 

of time zone names 308 
ArraySize 

TMArray As Vector member function 356 

TMI Array As Vector member function 361 
ASCII codes 

alphabetic 150 
lowercase 152 
uppercase 154 

alphanumeric 150 

control or delete 152 

converting 

characters to 282 
date and time to 30 

digits 152 
hexadecimal 154 

functions, list 10 

low 150 

lowercase alphabetic 152 

printing characters 152, 153 

punctuation characters 153 



uppercase alphabetic 154 

whitespace 154 
asctime (function) 30 
asin (complex friend function) 467 
asin (function) 30 
asinl (function) 30 
assert (function) 31 
assert_element 

string member function 500 

TSubString member function 505 
assert.h (header file) 7 
assert_index, string member function 500 
AssertDate, TTime member function 577 
AssertlndexOfMonth, TDate member function 486 
assertion 31 
AssertWeekDayNumber, TDate member function 

486 
assign, string member function 494 
assignment suppression, format specifiers 220, 

224, 225 
AsString 

TDate member function 484 

TTime member function 515 
atan (complex friend function) 467 
atan (function) 31 
atan2 (function) 32 
atan21 (function) 32 
atanl (function) 31 
ate, ios data member 319 
atexit (function) 33 
atof (function) 33 
atoi (function) 34 
atol (function) 35 
_atold (function) 33 
attach member functions 

filebuf 314 

fpbase 336 

fstreambase 317 
attribute bits 184, 243 
attribute word 61, 70, 214 
attributes 

characters, arrays of 300 

text 275, 277, 278 

B 

bad 

ios member function 320 
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pstream member function 344 
Bad_cast (class) 477 
Bad_typeid (class) 477 
banker's rounding 464 
base 10 logarithm 163, 468 
base, streambuf member function 331 
basefield, ios data memb er 318 
BCD (binary coded decimal) numbers 463, 465 
bed (class constructor) 463, 464 
bcd.h (header file) 7 
bdos (function) 35 
bdosptr (function) 36 
before, Type_info member function 480 
BeginDST, TTime member function 515 
_beginthread (function) 37 
JbeginthreadNT (function) 37 
Between 

TDate member function 484 

TTime member function 515 
binary, ios data member 319 
binary files 

creat and 59 

creattemp and 61 

fdopen and 96 

fopenand 107 

freopenand 112 

_fsopenand 116 

opening 96, 107, 1 12, 1 16 
and translating 305 

setting 235 

temporary 
naming 274, 281 
opening 280 
binary search 44 
BIOS 

functions (list) 13 

interrupts 
0x11 39, 40 
0x12 42,43 
0x16 41 
OxlA 43 

timer 43 
_bios_equiplist (function) 40 
bios.h (header file) 7 
_bios_memsize (function) 42 
_bios_timeofday (function) 43 
biosequip (function) 39 



bioskey (function) 41 
biosmemory (function) 42 
biostime (function) 43 
bit mask 117 
bit rotation 

long integer 165 

unsigned char 62 

unsigned integer 213 
bitalloc, ios member function 320 
bits, attribute 61, 69, 70, 184, 215, 243 
blen, streambuf member function 331 
blink-enable bit 276 
Borland C++ 

functions, licensing 3 

obsolete definitions 16 
BoundBase 

TArrayAsVectorlmp member function 363 

TMArray As Vector member function 358 
bp 

ios data member 319 

pstream data member 345 
bsearch (function) 44 
buffers 

default, allocating 344 

files 236, 313, 315 
allocating 336 
creating 336, 337, 340, 34 1 

pstream 344 
current 336 

keyboard, pushing character to 286 

pointers, pstream 345 

streams and 228, 229, 236, 313,315 
clearing 703 
flushing 94 
pointers to 345 
writing 103 

system-allocated, freeing 94 

writing data from 342 
BUILDER type, streamable classes and 347 
bytes 

copying 180 

reading from hardware ports 142, 143 

returning from memory 188 

storing in memory 192 

streamable objects and 338, 339, 340, 341, 342, 

348 

swapping 272 
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C++ See Borland C++ 

c_str, string member function 494 

cabs (function) 45 

cabsl (function) 45 

calendar format (time) 179 

calloc (function) 46 

carry flag 145, 146, 147 

CastablelD, TStreamableBase member function 

346 
ceil (function) 46 
ceill (function) 46 
cgets (function) 48 
_chain_intr (function) 48 
channels (device) 149 
characters 

alphabetic 150 

alphanumeric 150 

array 338 
global variable 300 

attributes 275, 277, 278 

blinking 276 

color, setting 275, 278 

control or delete 152 

converting to ASCII 282 

device 151 

digits 152 

displaying 197, 201, 221 

floating-point numbers and 33 

functions (list) 10 

hexadecimal digits 154 

intensity 
high 141 
low 165 
normal 182 

low ASCII 150 

lowercase 282 
checking tor 152 
converting to 282 

manipulating header file 8 

newline (\n) 203 

printing 152, 153 

punctuation 153 

pushing 
to input stream 286 
to keyboard buffer 286 

reading 221 



from console 48 
from keyboard 122, 123 
from streams 98, 122, 123 
stdin 98 
scanning in strings 255, 264 

segment subset 266 
searching 
blocks 174 
strings 252 
streamable objects and 338, 342 
uppercase 
checking for 154 
converting to 283 
whitespace 154 
writing 
to screen 201 
to streams 110, 201, 202 
chdir (function) 49 
_chdrive (function) 49 
CHECK macro 472 
checks.h (header file) 7 
CHECKX macro 473 
child processes 87, 244 
exec (function) 22 
functions (list) 17 
header file 8 
spawn (function) 22 
chmod (function) 50 
chsize (function) 51 
class diagnostics 471 
CHECK macro 471 
CHECKX macro 471 
PRECONDITION macro 471 
PRECONDITIONX macro 471 
TRACE macro 471 
TRACEX macro 471 
WARN macro 471 
WARNX macro 471 
classes 
, names, read/write prefix/suffix 339 
registering 339, 342, 347 
writing to streams 343 
clear 

ios member function 320 
pstream member function 344 
_clear87 (function) 51 
clearerr (function) 52 
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clearing 

screens 54 

to end of line 54 
clock (function) 52 
close (function) 53 
Close, TFile member function 490 
close member functions 

filebuf 314 

fpbase 336 

fstreambase 317 
closedir (function) 53 
clreol, conbuf member function 311 
clreol (function) 54 
clrscr (function) 54 
clrscr member functions 

conbuf 31 1 

constream 313 
co-routines, task states and 164 
colors and palettes 

background color, text 275, 277 

setting, character 275, 278 
command-line arguments, passing to main 299, 

300 
command-line compiler, Pascal calling conventions, 

option (-p) 22 
communications, ports, checking for 39, 40, 151 
compare, string member function 494 
CompareTo 

TDate member function 484 

TTime member function 515 
comparing two values 171, 177 
comparison function, user-defined 205 
compile-time limitations, header file 8 
complex (class constructor) 466 
complex.h (header file) 7 
complex numbers 

absolute value 45 
square of 468 

angles 467 

conjugate of 467 

constructor for 466 

conversion to real 466 

functions (list) 15 

header file 7 

imaginary portion 468 

logarithm 468 

polar function 468 



real portion 468 l 

COMSPEC environment variable 273 
conbuf (class) 311 
concatenated strings 252, 261 
CondFunc typedef 355, 360, 374, 376, 383, 387, 

390, 392, 402, 407, 417, 421, 437, 439, 444, 453 
conditions, testing 31 
conio.h (header file) 8 
conj (complex friend function) 467 
conjugate (complex numbers) 467 
console 

checking for 151 

header file 8 

output flag 301 

reading and formatting 
characters 48 
input 63 
constants 

DOS (header file) 8 

open function (header file) 8 

symbolic (header file) 9 

UNIX compatible (header file) 9 

used by function setf 318 
constrea.h (header file) 8 
constream (class) 313 
constructors 

complex numbers 466 

conbuf 311 

filebuf 314 

fpbase 336 

f stream 316 

fstreambase 316 

ifpstream 337 

ifstream377 

iostream 322 

iostream_withassign 323 

ipstream 337, 339 

istream 323 

istream_withassign 325 

istrstream 326 

ofpstream 340 

ofstream 326 

opstream 341,343 

ostream 327 

ostream_withassign 328 

ostrstream 328 

pstream 344, 345 
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streambuf 320, 329 
strstream 334 
strstreambase 332 
strstreambuf 333 
TStreamableClass 347 
contains, string member function 494 
_control87 (function) 55 
control-break 
handler 64 
returning 122 
setting 229 
software signal 206 
control characters, checking for 152 
control word, floating point 55 
conversions 

binary coded decimal 463, 465 
complex numbers 466 
date and time 30 

to calendar format 1 79 

DOS to UNIX format 81 

to Greenwich mean time 135 

header file 9 

to string 63 

to structure 160 

UNIX to DOS format 287 
double 

to integer and fraction 180 

to mantissa and exponent 113 

strings to 267 
floating point 

strings to 33 

to string 84, 95, 121 
format specifiers 196, 200 
functions (list) 10 
header file 9 
integer 

strings to 34 

to ASCII 282 

to string 155 
long double, strings to 267 
long integer 

strings to 35, 269,270 

to string 1 67, 285 
lowercase to uppercase 270, 283 
specifications (printf) 195 
strings 

date and time to 63 



integers to 155 

to double 267 

to floating point 33 

to integer 34 

to long double 267 

to long integer 35, 269, 270 

to unsigned long integer 270 
unsigned long integer 

strings to 270 

to string 285 
uppercase to lowercase 260, 282 
coordinates 

cursor position 136, 296 
screens, text mode 132 
copy, string member function 494 
coroutines, task states and 231 
cos (complex friend function) 467 
cos (complex numbers) 467 
cos (function) 55 

cosh (complex friend function) 467 
cosh (complex numbers) 467 
cosh (function) 56 
coshl (function) 56 
cosine 55, 467 
hyperbolic 56 

complex numbers 467 
inverse 28 
cosl (function) 55 

Count, TMCVectorlmp member function 449 
country (function) 57 
country-dependent data 57, 158, 232 
cow, string member function 50 1 
cprintf (function) 58 

format specifiers 195 
cputs (function) 59 
creat (function) 59 
creatnew (function) 60 
creattemp (function) 61 
_crotl (function) 62 
_crotr (function) 62 
cscanf (function) 63 

format specifiers 219 
cstring (header file) 8 
ctime (function) 63 
ctrlbrk (function) 64 
_ctype (global variable) 300 
ctype.h (header file) 8 
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currency symbols 58, 158, 232 
Current 

TBinarySearchTreelteratorlmp member function 

380 

TIBinarySearchTreelmp member function 382 

TMArrayAsVectorlterator member function 359 

TMDequeAsVectorlterator member function 

386 

TMDictionaryAsHashTablelterator member 

function 396 

TMDoubleListlteratorlmp member function 404 

TMHashTablelteratorlmp member function 413 

TMIArrayAsVectorlterator member function 

364 

TMIDictionaryAsHashTablelterator member 

function 399 

TMIDoubleListlteratorlmp member function 

409 

TMIHashTablelteratorlmp member function 

415 

TMIListlteratorlmp member function 423 

TMIVectorlteratorlmp member function 455 

TMListlteratorlmp member function 419 

TMVectorlteratorlmp member function 447 
current drive number 126 
cursor 

appearance, selecting 230 

position in text window 136 
returning 296 
cwait (function) 65 



data 

country-dependent, supporting 57, 158, 232 

moving 180 

reading from streams 111,1 13, 290, 293 
stdin 219, 292 

returning from current environment 727 

security 130 

writing to current environment 202 
Data, TMDequeAs Vector data member 385 
data public members 

TMDoubleListElement 401 

TMListElement476 
data segment 46, 169 
data types 

defining header file 9 



time_t (header file) 9 
date 
, file 76, 129 

global variable 300 

international formats 57 

system 30, 63, 1 19, 135, 160 
converting from DOS to UNIX 8 1 
converting from UNIX to DOS 287 
getting 73 
setting 73, 251 
date functions (list) 18 
Day, TDate member function 484 
_daylight (global variable) 300 

setting value of 283 
daylight saving time 

adjustments 64,300 

setting 284 
DayName, TDate member function 484 
DayOfMonth, TDate member function 485 
DayOfWeek, TDate member function 485 
DaysInYear, TDate member function 485 
DayTy, TDate type definition 483 
DayWithinMonth, TDate member function 485 
de_exterror 71 

_ _DEBUG debugging symbol 471 
debugging 

classes 471 

macros (header file) 7 
dec, ios data member 319 
delete 

TMDoubleListElement operator 401 

TMListElement operator 417 
DeleteNode 

TBinarySearchTreelmp member function 380 

TIBinarySearchTreelmp member function 382 
DeleteType, TShouldDelete data member 461 
deletion 

characters, checking for 152 

directories 212 

file 210, 287 

line 54, 66 
delline, conbuf member function 312 
delline (function) 66 
DelObj 

TShouldDelete member function 461 
DELTA macro 349 

TStreamableClass 348 
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Destroy 

TMArray As Vector member function 356 
TMI Array As Vector member function 36 1 

destructor 
opstream 341 
pstream 344 

Detach 

TBinarySearchTreelmp member function 379 
TIBinarySearchTreelmp member function 381 
TMArray As Vector member function 356 
TMBagAs Vector member function 374 
TMCVectorlmp member function 449 
TMDictionaryAsHashTable member function 
396 

TMDoubleListlmp member function 402 
TMHashTablelmp member function 412 
TMIArray As Vector member function 361 
TMIBagAs Vector member function 377 
TMIDictionaryAsHashTable member function 
398 

TMIDoubleListlmp member function 407 
TMIHashTablelmp member function 414 
TMIListlmp member function 421 
TMListlmp member function 418 

DetachAtHead, TMIDoubleListlmp member function 
408 

DetachAtTail, TMIDoubleListlmp member function 
408 

device 

channels 149 
character 151 
DOS drivers 149 
type checking 151 

DIAG_CREATE_GROUP macro 474 

DIAG_DECLARE_GROUP 474 

DIAG_DEFINE_GROUP macro 474 

DIAG.ENABLE macro 474 

DIAG_GETLEVEL macro 474 

DIAGJSENABLED macro 474 

DIAG_SETLEVEL macro 474 

diagnostics 
class 471 
preprocessor symbols 471 

difftime (function) 66 

dir.h (header file) 8 

direct.h (header file) 8 



direct memory access (DMA) 

checking for presence of 39, 4 1 
directories 

creating 178 

current 88, 245 
changing 49 
returning 124, 125 

deleting 212 

functions (list) 1 1 

header file 8 

searching 53, 71, 72, 100, 102, 185, 208,211, 
226, 227 
directory stream 

closing 53 

opening 185 

reading 208 

rewinding 211 
_directvideo (global variable) 301 
dirent.h (header file) 8 
disable (function) 67 
_disable (function) 67 
disk drives 

checking for presence of 39, 41 

current number 75,126 

setting 49 
disk transfer address (DTA) 

DOS 
returning 127 
setting 230 
disks 

space available 74, 126 

writing to, verification 135, 237 
div (function) 67 
division, integers 67, 157 
DLL, memory model support 7 
DMA See direct memory access 
doallocate, strstreambuf member function 333 
DOS 

date and time 73 
converting to UNIX format 81 
converting UNIX to 287 
setting 133 

device drivers 149 

environment, adding data to 202 

error codes 303 

error information, extended 70 

file attributes, search 101 
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functions (list) 13 
header file 8 
interrupts 

0x21 146, 147 

0\23 64 

functions 78, 81, 134 

interface 146, 147 
system calls 

0x29 187 

0x33 122, 229 

0x44 148 

0x59 71 

0x62 131 

accessing 35, 36 

memory models and 36 
verify flag 134 
_dos_getvect (function) 78 
_dos_setvect (function) 81 
_dos_close (function) 68 
_dos_commit (function) 68 
_dos_creat (function) 69 
_dos_creatnew (function) 69 
_doserrno (global variable) 302, 303 
dosexterr (function) 70 
_dos_findfirst (function) 71 
_dos_findnext (function) 72 
_dos_getdate (function) 73 
_dos_getdiskfree (function) 74 
_dos_getdrive (function) 75 
_dos_getfileattr (function) 75 
_dos_getftime (function) 76 
_dos_gettime (function) 77 
dos.h (header file) 8 
_dos_open (function) 78 
_dos_read (function) 79 
_dos_setdate (function) 73 
_dos_setdrive (function) 75 
_dos_setfileattr (function) 75 
_dos_setftime (function) 76 
_dos_settime (function) 77 
dostounix (function) 81 
_dos_write (function) 82 
DTA See disk transfer address 
dup (function) 82 
dup2 (function) 83 
dynamic_cast (exception) 477 
dynamic-link libraries See DLL 



dynamic memory allocation 46, 111, 169, 209, 250 



eatwhite, istream member function 325 
eback, streambuf member function 331 
ebuf, streambuf member function 331 
echoing to screen 122, 123 
ecvt (function) 84 
editing, block Operations 

copying 174, 175, 176, 181 

searching for character 1 74 
egptr, streambuf member function 331 
_8087 (global variable) 299 
_ _emit_ _ (function) 84 
enable (function) 67 
_enable (function) 67 
encryption 130 
end of file 

checking 86, 96, 208 

resetting 52 
end of line, clearing to 54 
_endthread (function) 86 
enum open_mode, ios data member 319 
env (argument to main) 19 
_environ (global variable) 20, 301 
environment 

operating system (header file) 8 

variables 307 
COMSPEC 272 
PATH 88, 245 
eof 

ios member function 320 

pstream member function 344 
eof (function) 86 

epptr, streambuf member function 331 
EqualTo 

TBinarySearchTreelmp member function 380 

TIBinarySearchTreelmp member function 382 
equations, polynomial 192 
errno (global variable) 302 
errno.h (header file) 8 
error codes 302 

error handlers, math, user-modifiable 169 
errors 

detection, on stream 96, 97 

DOS 
extended information 70 
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mnemonics 302, 303 

indicators, resetting 52 

locked file 161 

messages 
perror function 189 
pointer to, returning 256, 257 
printing 189, 302 

mnemonics for codes 8 

read /write 97 

streams and 344, 345 
ErrorType, TThreadError data member 514 
European date formats 57 
except.h (header file) 8 

exception handlers, numeric coprocessors 52, 251 
exception handling 

exception names 307 

files 307 

global variables 307 

messages 482 

predefined exceptions 477, 481, 482 

set_terminate (function) 478 

set_unexpected (function) 479 

terminate (function) 479 

unexpected (function) 481 
exceptions 

Bad_cast (class) 477 

Badjypeid (class) 477 

floating-point 55 

memory allocation 478, 481 

xalloc 478, 481 

xmsg (class) 482 
excpt.h (header file) 8 
execl (function) 87 
execle (function) 87 
execlp (function) 87 
execlpe (function) 87 
execution, suspending 242 
execv (function) 87 
execve (function) 87 
execvp (function) 87 
execvpe (function) 87 
exit (function) 33, 47, 90 
_exit (function) 89 
exit codes 27 
exit status 89, 90 

exp (complex friend function) 467 
exp (function) 90 



_expand (function) 91 

expl (function) 90 

exponential (complex numbers) 467 

exponents 

calculating 90, 193, 194 

double 113, 156 
extended error information, DOS 70 
external, undefined 16 



fabs (function) 91 
fabsl (function) 91 
fail 

ios member function 320 

pstream member function 344 
far heap 

allocating memory from 92, 93 

memory in 
freeing 92 
reallocating 93 

pointers 92, 93, 94 
farcalloc (function) 92 
farfree (function) 92 

small and medium memory models and 92 
farmalloc (function) 93 
farrealloc (function) 93 
FAT See file allocation table 
fclose (function) 94 
fcloseall (function) 94 
fcntl.h (header file) 8 
fcvt (function) 95 
id, filebuf member function 314 
fdopen (function) 95 
feof (function) 96 
ferror (function) 97 
fflush (function) 97 
fgetc (function) 98 
fgetchar (function) 98 
fgetpos (function) 98 
fgets (function) 99 
fields, input 222, 225 
file allocation table (FAT) 128 
file modes 

changing 50, 75,213 

default 61, 69, 70, 215 

global variables 305 

setting 235, 305 
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text 96, 107, 1 12, 1 16 
translation 59, 61, 305 
file permissions 285 
filebuf (class) 313 
filelength (function) 99 
fileno (function) 700 
FileNull, TFile data member 488 
files 
access 

determining 28 

flags 184, 243 

permission 50 
ARGS.EXE 20 
attaching 336, 337, 340, 341 
attribute bits 184, 243 
attribute word 214 
attributes 60 

access mode 75, 213 

file sharing 79, 21 7 

searching directories and 71, 101 

setting 61, 69, 70, 215 
buffers 236 

allocating 336 

current 336 

input and output 313,315 

line 236 
closing 53, 68, 94, 1 12, 214, 336 
date 76, 129 
deleting 210, 287 
end of 

checking 86, 96, 208 

resetting 52 
file descriptor fd (function) 314 
file pointer reposition 315 
handles 53, 68, 184, 214 

duplicating 82, 83 

linking to streams 95 

returning 100 
header 25 

HPFSandNTES 117 
information on, returning 116 
locking 161, 288 
modes, setting 336, 337, 340, 341 
names 

parsing 187 

unique 179,274,281 
new 59, 60, 61, 69, 214 



open, statistics on 116 

opening 78, 183, 184, 216, 336, 337, 341 

for update 96, 108, 1 12, 1 16 
in binary mode 280 

for writing 340 

modes 319, 337, 341 
default 314 

openprot 314 

shared 1 15, 242, 243 

streams and 107, 1 12, 1 15 
overwriting 60 
position seeking 318 
reading 60, 79, 207, 217 

and formatting input from 1 13, 219, 290, 292, 

293 

characters from 98, 122 

data from 111 

header file 8 

integers from 735 

strings from 99 
renaming 270 
replacing 772 
rewriting 59, 69, 214 
scratch 274, 281 

opening 280 
security 730 
seek an offset 315 
sharing 

attributes 70,277 

header file 9 

locks 767, 288 

opening shared files 7 15, 242, 243 

permission 7 16, 243 
size 51 

returning 99 
statistics 770 

streams, C++ operations 370 
temporary 274, 281 

opening 280 

removing 272 
time 76, 129 
unlocking 288 
WILDARGS.OBJ 27, 22 
writing 82, 120, 218, 298 

attributes 60 

characters to 770 

formatted output to 700, 195,290,291 
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header file 8 
strings to 110 

fill, ios member function 320 

Find 

TBinarySearchTreelmp member function 379 

TIBinarySearchTreelmp member function 381 

TMArrayAsVector member function 358 

TMBagAs Vector member function 375 

TMCVectorlmp member function 449 

TMDictionaryAsHashTable member function 

396 

TMHashTablelmp member function 412 

TMIArrayAsVector member function 362 

TMICVectorlmp member function 457 

TMIDictionaryAsHashTable member function 

398 

TMIHashTablelmp member function 4 14 

find 

ipstream member function 337 
string member function 495 

find_first_not_of, string member function 495 

find_first_of, string member function 495 

find_last_not_of, string member function 496 

find_last_of, string member function 496 

FindBase, TStreamableBase member function 347 

FindDetach 

TMDoubleListlmp member function 403 
TMISDoubleListlmp member function 410 
TMISListlmp member function 424 
TMListlmp member function 419 
TMSDoubleListlmp member function 406 

findfirst (function) 100 

FindMember 

TMBagAs Vector member function 374 
TMIBagAs Vector member function 377 

findnext (function) 102 

findObject, opstream member function 34 1 

FindPred 

TMDoubleListlmp member function 404 
TMIDoubleListlmp member function 409 
TMISListlmp member function 424 
TMListlmp member function 419 
TMSDoubleListlmp member function 406 

findVB, opstream member function 34 1 

FirstDayOfMonth, TDate member function 485 

FirstThat 

TMArrayAsVector member function 356 



TMDequeAsDoubleList member function 390 

TMDequeAs Vector member function 383 

TMDoubleListlmp member function 402 

TMIArrayAsVector member function 362 

TMIBagAsVector member function 377 

TMIDequeAsDoiibleList member function 393 

TMIDequeAs Vector member function 387 

TMIDoubleListlmp member function 408 

TMIListlmp member function 422 

TMIQueueAsDoubleList member function 431 

TMIQueueAs Vector member function 427 

TMIStackAs Vector member function 440 

TMIVectorlmp member function 454 

TMListlmp member function 418 

TMQueueAsDoubleList member function 429 

TMQueueAs Vector member function 425 

TMStackAs Vector member function 437 

TMVectorlmp member function 445 
fixed, ios data member 319 
flags 

carry 145, 146, 147 

console output 301 

DOS verify 134 

format specifiers 196, 198 

format state 345 

ios member function 320 

operating system verify 237 

read /write 184, 243 

video output 301 
float.h (header file) 8 
_floatconvert (global variable) 304 
floatfield, ios data member 318 
floating point 

absolute value of 91 

binary coded decimal 463, 465 

characters and 33 

control word 55 

displaying 197, 223 

double, exponents 156 

exceptions 55 

format specifiers 197,221,223 

formats 304 

functions (list) 15 

header file 8 

I/O 304 

infinity 55 

math package 108 



Index 



531 



modes 55 
precision 55 
reading 221 
software signal 206 
status word 51,251 

floor (function) 103 

floorl (function) 703 

Flush 

TBinarySearchTreelmp member function 379 
TFile member function 490 
TIBinarySearchTreelmp member function 381 
TMArrayAs Vector member function 357 
TMBagAs Vector member function 374 
TMDequeAsDoubleList member function 390 
TMDequeAs Vector member function 383 
TMDictionaryAsHashTable member function 
396 

TMDoubleListlmp member function 403 
TMHashTablelmp member function 4 12 
TMIArrayAs Vector member function 362 
TMIBagAs Vector member function 377 
TMIDequeAsDoubleList member function 393 
TMIDequeAsVector member function 388 
TMIDictionaryAsHashTable member function 
398 

TMIDoubleListlmp member function 408 
TMIHashTablelmp member function 414 
TMIQueueAsDoublelist member function 432 
TMIQueueAsVector member function 428 
TMIStackAs Vector member function 440 
TMIVectorlmp member function 454 
TMListlmp member function 418 
TMQueueAsDoubleList member function 430 
TMQueue As Vector member function 425 
TMStackAs Vector member function 437 
TMVectorlmp member function 445 

flush 

opstream member function 34 1 
ostream member function 327 

flushall (function) 103 

flushing streams 97, 103 

_fmemccpy (function) 1 74 

_fmemchr (function) 1 74 

_fmemcmp (function) 175 

_fmemcpy (function) 1 75 

_f memicmp (function) 176 

_fmemmove (function) 176 



_fmemset (function) 177 

fmod (function) 104 

_fmode (global variable) 305 

fmodl (function) 104 

_f mo vmem (function) 181 

fname, Type_info member function 481 

fnmerge (function) 105 

fnsplit (function) 106 

fopen (function) 107 

ForEach 

TBinarySearchTreelmp member function 379 
TIBinarySearchTreelmp member function 381 
TMArrayAsVector member function 357 
TMBagAs Vector member function 375 
TMDequeAsDoubleList member function 390 
TMDequeAs Vector member function 384 
TMDictionaryAsHashTable member function 
396 

TMDoubleListlmp member function 403 
TMIArrayAsVector member function 362 
TMIBagAs Vector member function 377 
TMIDequeAsDoubleList member function 393 
TMIDequeAsVector member function 388 
TMIDictionaryAsHashTable member function 
398 

TMIDoubleListlmp member function 408 
TMIHashTablelmp member function 412, 414 
TMIListlmp member function 422 
TMIQueequeAs Vector member function 428 
TMIQueueAsDoubleList member function 432 
TMIStackAs Vector member function 440 
TMIVectorlmp member function 454 
TMListlmp member function 4 18 
TMQueueAsDoubleList member function 430 
TMQueueAs Vector member function 425 
TMStackAs Vector member function 437 
TMVectorlmp member function 445 

format flags 318, 319 
state 345 

format specifiers 

assignment suppression 220, 224, 225 
characters 197,221 

type 220, 221 
conventions 
, display 197 
reading 222 
conversion type 196, 200 
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cprintf 195 
cscanf 219 
F and N 196 
flags 196, 198 

alternate forms 198 
floating-point 197, 221, 223 
fprintf 195 
fscanf 219 

inappropriate character in 225 
input fields and 222,225 
integers 196, 221 
modifiers 

argument-type 220, 225 

input-size 196, 200 

size 220, 225 
pointers 197, 222 
precision 196, 199, 200 
printf 195 

range facility shortcut 223 
scant 219 
sprintf 195, 248 
sscanf 219 
strings 197, 221 
vfprintf 195 
vfscanf 219 
vprintf 195 
vscanf 219 
vsprintf 195 
vsscanf 219 
width 

printf 196,198 

scanf 220, 224, 225 
format strings 
input 219 
output 195 
formatting 

console input 63 
cprintf 58 
cscanf 63 
fprintf 109 
fscanf 1 13 
output 58 
printf 195 
scanf 219 
sprintf 248 
sscanf 250 
strings 248, 293 



time 257 

vfprintf 290 

vfscanf 290 

vprintf 291 

vscanf 292 

vsprintf 293 

vsscanf 293 
FP_OFF (function) 108 
FP_SEG (function) 108 
fpbase class 336 
_f preset (function) 108 
fprintf (function) 109 

format specifiers 195 
fputc (function) 110 
fputchar (function) 110 
fputs (function) 110 

frame base pointers as task state 164, 231 
fread (function) 111 

freadBytes, ipstream member function 337 
freadString, ipstream member function 338 
free (function) 111 

freeze, strstreambuf member function 333 
freopen (function) 1 12 
frexp (function) 113 
frexpl (function) 113 
fscanf (function) 113 

format specifiers 219 
fseek (function) 114 
fsetpos (function) 115 
_fsopen (function) 115 
fstat (function) 1 16 
_fstrcat (function) 252 
_fstrcmp (function) 253 
_fstrchr (function) 252 
_fstrcpy (function) 255 
_fstrcspn (function) 255 
_fstrdup (function) 256 
fstream (class) 315 
fstream.h (header file) 8 
fstreambase (class) 316 
_fstricmp (function) 259 
_fstrlen (function) 260 
_fstrlwr (function) 260 
_fstrnbrk (function) 264 
_fstrncat (function) 261 
_fstrncmp (function) 261 
_fstrncpy (function) 262 
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_fstrincmp (function) 263 
_fstrnset (function) 263 
_fstrrchr (function) 264 
_fstrrev (function) 265 
_fstrset (function) 265 
_fstrspn (function) 266 
Jfstrstr (function) 266 
Jstrtok (function) 268 
_fstrupr (function) 270 
ftell (function) 118 
ftime (function) 119 
Jullpath (function) 120 
functions 

8086 13 

bed (header file) 7 

BIOS 13 
header file 7 

Borland C++, licensing 3 

child processes 17 
header file 8 

classification 10 

comparing two values 171 

comparison, user-defined 205 

complex numbers 15 
header file 7 

console (header file) 8 

conversion 10 

date and time 18 
header file 9 

diagnostic 11 

directories 1 1 
header file 8 

file sharing (header file) 9 

floating point (header file) 8 

fstream (header file) 8 

generic (header file) 8 

goto 16 
header file 9 

integer 15 

international 
header file 8 
information 16 

I/O 12 
header file 8 

iomanip (header file) 8 

iostream (header file) 8 

listed by topic 9-18 



locale 16 

mathematical 15 
header file 8 

memory 14 
allocating and checking 16 
header file 8 

obsolete names 17 

operating system 13 

process control 17 

signals (header file) 9 

sound 16 

stdiostr (header file) 9 

strings 14 

strstrea (header file) 9 

variable argument lists 18 

windows 10 

with multiple prototypes 9 
fwrite (function) 120 

fwriteBytes, opstream member function 34 1 
fwriteString, opstream member function 342 



game port 39, 40 

gbump, streambuf member function 331 

gcount, istream member function 323 

gcvt (function) 12 1 

generic.h (header file) 8 

geninterrupt (function) 121 

Get 

TMIQueueAsDoubleList member function 432 
TMIQueueAs Vector member function 428 
TMQueueAsDoubleList member function 430 
TMQueueAs Vector member function 426 

get, istream member function 323, 324 

get_at 

string member function 496 
TSubString member function 505 

get_case_sensitive_flag, string member function 
496 

get_initial_capacity, string member function 496 

get_max_waste, string member function 496 

get_paranoid_check, string member function 497 

get_resize_increment, string member function 497 

get_skipwhitespace_flag, string member function 
497 

getc (function) 122 

getcbrk (function) 122 
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getch (function) 122 

getchar (function) 123 

getche (function) 123 

getcurdir (function) 124 

getcwd (function) 124 

getdate (function) 73 

_getdcwd (function) 125 

GetDelta 

TMCVectorlmp member function 450 
TMIVectorlmp member function 454 
TMVectorlmp member function 445 

getdfree (function) 126 

getdisk (function) 126 

getdta (function) 127 
memory models and 127 

getenv (function) 127 

GetErrorType, TThreadError member function 514 

getfat (function) 128 

getfatd (function) 128 

getftime (function) 129 

GetHandle, TFile member function 490 

GetltemsInContainer 

TBinarySearchTreelmp member function 379, 
381 

TMArray As Vector member function 357 
TMBagAs Vector member function 375 
TMDequeAsDoubleList member function 391 
TMDequeAs Vector member function 384 
TMDictionaryAsHashTable member function 
396 

TMDoubleListlmp member function 408 
TMHashTablelmp member function 4 12 
N TMI Array As Vector member function 362 
TMIBagAsVector member function 377 
TMIDequeAsDoubleList member function 393 
TMIDequeAs Vector member function 388 
TMIDictionaryAsHashTable member function 
398 

TMIHashTablelmp member function 415 
TMIQueueAsDoubleList member function 432 
TMIQueueAs Vector member function 428 
TMQueueAsDoubleList member function 430 
TMQueueAs Vector member function 426 
TMStackAs Vector member function 437, 440 

GetLeft 

TMDequeAsDoubleList member function 391 
TMDequeAs Vector member function 384 



TMIDequeAsDoubleList member function 393 

TMIDequeAs Vector member function 388 
getline 

global string function 504 

istream member function 324 
GetObject, TStreamer member function 348 
getpass (function) 130 
getpid (function) 130 

GetPriority, TThread member function 512 
getpsp (function) 130 
GetRight 

TMDequeAsDoubleList member function 391 

TMDequeAs Vector member function 384 

TMIDequeAsDoubleList member function 393 

TMIDequeAsVector member function 388 
gets (function) 131 
GetStatus 

TFile member function 490 

TThread member function 512 
gettext (function) 131 
gettextinfo (function) 132 
gettime (function) 133 
getvect (function) 134 
getverify (function) 134 
getVersion, ipstream member function 338 
getw (function) 135 
global variables 299 

_8087 299 

_avgc 299 

_argv 300 

arrays, character 300 

command-line arguments 299, 300 

_ctype 300 

_daylight 300 

setting value of 283 

_directvideo 301 

_doserrno 302, 303 

_environ 20, 301 

errno302 

file mode 305 

_floatconvert 304 

_fmode 305 

main function and 299, 300 

_new_handler 305 

numeric coprocessors and 299 

obsolete names 16 

operating system environment 301 
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_osmajor 306 

_osminor 306 

_osversion 306 

printing error messages 302 

program segment prefix (PSP) 307 

_psp 307 

_sys_errlist 302 

_sys_nerr 302 

time zones 300, 308 
setting value of 283 

_timezone 308 

setting value of 283 

_tzname 308 

setting value of 283 

undefined 16 

_version 308 

video output flag 307 
gmtime (function) 135 
good 

ios member function 327 

pstream member function 345 
goto, nonlocal 64, 164, 231 
goto statements 

functions list 16 

header file 9 
gotoxy, conbuf member function 372 
gotoxy (function) 136 
gptr, streambuf member function 337 
graphics drivers, modes, text 737, 732 
Greenwich mean time (GMT) 64, 67, 1 19 

converting to 735 

global variable 308 

time zones and 284, 308 
Grow 

TMArrayAs Vector member function 358 

TMIArrayAs Vector member function 363 

H 

handlers 239 

exception 52, 251 

interrupt 64 
hardware 

checking for presence of 39, 40, 151 
device type 151 

I/O, controlling 148 

interrupts 39, 40 

ports 742, 743 



reading from 743, 744 
writing to 785, 186 
Hash 

TDate member function 485 

TTime member function 575 
hash, string member function 497 
HashTable, TMDictionaryAsHashTable data member 

395 
Hash Value 

TMDDAssociation member function 368 

TMDIAssociation member function 370 

TMIDAssociation member function 377 

TMIIAssociation member function 373 
HasMember 

TMArrayAsVector member function 357 

TMBagAs Vector member function 375 

TMIArrayAs Vector member function 362 

TMIBagAs Vector member function 378 
Head 

TMDoubleList data member 403 

TMListlmp data member 419 
header files 25 

described 7 

floating point 8 

reading and writing 8 

sharing 9 
heap 

allocating memory from 46, 111, 169,209 

checking 737, 738 

free blocks 
checking 737 
filling 139, 140 

memory freeing in 77 7 

nodes 738 

reallocating memory in 209 

walking through 740, 275 
_heapadd (function) 737 
heapcheck (function) 737 
heapcheckfree (function) 737 
heapchecknode (function) 738 
_heapchk (function) 738 
_HEAPEMPTY 747 
_HEAPEND 740, 747 
JiEAPOK 740 
heapfillfree (function) 730 
_heapmin (function) 730 
HEAPOK 747 
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_heapset (function) 140 

heapwalk (function) 140 

hex, ios data member 319 

hexadecimal digits, checking for 154 

hierarchy, streams 335 

high intensity 141 

highvideo, conbuf member function 312 

highvideo (function) 141 

Hour, TTime member function 516 

HourGMT, TTime member function 516 

HowToPrint, TDate type definition 483 

hyperbolic cosine 56 

hyperbolic sine 241 

hyperbolic tangent 273, 469 

hypot (function) 141 

hypotenuse 141 

hypotl (function) 141 

I 

ID, process 130 

ifpstream class 336 

if stream (class) 317 

ignore, istream member function 324 

illegal instruction, softvyare signal 206 

imag (complex friend function) 468 

in, ios data member 319 

in_avail, streambuf member function 330 

IndexOfMonth, TDate member function 485 

indicator 

end-of-file 52, 86, 96, 208 

error 52 
infinity, floating point 55 
init 

ios member function 322 

pstream member function 346 
initial_capacity, string member function 497 
initialization 

file pointers 211 

memory 1 77, 235 

random number generator 207, 249 

strings 263, 265 
inline optimization 12 
inp (function) 142 
inport (function) 143 
inportb (function) 143 
input 

console, reading and formatting 63 



fields 222 

format specifiers and 225 
from streams 1 13, 290, 293 
formatting 1 13, 219, 290, 292, 293 
pushing characters onto 286 
stdin 219, 292 
terminating 226 

inpw (function) 144 

insert, string member function 497 

InsertEntry 

TMArray As Vector member function 358 
TMIArrayAsVector member function 363 

insline (conbuf member function) 312 

insline (function) 144 

int 

TBinarySearchTreelteratorlmp operator 380 
TIBinarySearchTreelteratorlmp operator 382 
TMArray AsVectlterator operator 360 
TMDequeAsVectorlterator operator 386 
TMDictionaryAsHashTablelterator operator 397 
TMDoubleListlteratorlmp operator 404 
TMHashTablelteratorlmp operator 413 
TMIDictionaryAsHashTablelterator operator 
399 

TMIHashTablelteratorlmp operator 415 
TMIVectorlteratorlmp operator 456 
TMListlteratorlmp operator 419 
TMVectorlteratorlmp operator 447 

int86 (function) 145 

int86x (function) 145 

intdos (function) 146 

intdosx (function) 147 

integers 

absolute value 27 
displaying 196 
division 67 

long integers 157 
format specifiers 196, 221 
functions (list) 15 
long 
absolute value of 156 
division 157 
rotating 165 
ranges, header file 8 
reading 135, 221 
rotating 165, 213 
storing in memory 19 1 
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writing to stream 204 
integrated environment, wildcard expansion and 

22 
intensity 

high 141 

low 165 

normal 182 
internal, ios data member 375 
international 

character sets 232 

code pages 232 

code sets 232 

country-dependent data 57 
setting 158, 232 

currency symbol position 159 

date formats 57 

decimal point 197, 222 

default category 234 

functions list 16 

header file 8 

locale library 7 

locales supported 232 

specify a category 234 
interrupts 

8086 145, 147 

chaining 48 

control-break 122, 229 

controlling 67, 121 

disabling 67 

enabling 67 

handlers 49 
DOS 64 
signal handlers and 239 

non-maskable 67 

software 121, 145, 148 
interface 145,147 
signal 206 

system equipment 39, 40 

vectors 64 

8086 78, 81, 134 
getting 134 
setting 81, 134 
intr (function) 147 
invalid access to storage 206 
inverse cosine (complex numbers) 466 
inverse sine (complex numbers) 467 
inverse tangent 32 



complex numbers 467 
io.h (header file) 8 
ioctl (function) 148 
I/O 

buffers 228 

characters, writing 201, 202 

controlling 148 

floating-point 

formats, linking 304 
numbers 304 

functions (list) 12 

integers, writing 204 

keyboard 122, 123 

checking for keystrokes 155 

low level header file 8 

ports 
hardware 142, 143, 144 
writing to 185, 186 

screen 58 
writing to 59, 201 

streams 96, 108, 1 12, 1 16, 286 
iomanip.h (header file) 8 
ios (class) 318 
ios data members 318 
iostream (class) 322 
iostream.h (header file) 8 
iostream_withassign (class) 322 
ipfx, istream member function 324 
ipstream class 337 

friends 340 
is_null 

String member function 497 

TSubString member function 505 
is_rtl_open, filebuf member function 314 
isalnum (function) 150 
isalpha (function) 750 
isascii (function) 750 
isatty (function) 757 
iscntrl (function) 757 
isdigit (function) 752 
IsDST, TTime member function 575 
IsEmpty 

TBinarySearchTreelmp member function 379, 

381 

TMArray As Vector member function 357 

TMBagAsVector member function 375 

TMDequeAsDoubleList member function 397 
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TMDequeAs Vector member function 384 
TMDictionaryAsHashTable member function 
396 

TMDoubleListlmp member function 403 
TMHashTablelmp member function 412 
TMIArrayAsVector member function 362 
TMIBagAs Vector member function 378 
TMIDequeAsDoubleList member function 393 
TMIDequeAsVector member function 388 
TMIDictionaryAsHashTable member function 
399 

TMIDoubleListlmp member function 408 
TMIHashTablelmp member function 415 
TMIQueueAsDoubleList member function 432 
TMIQueueAsVector member function 428 
TMIStackAs Vector member function 440 
TMListlmp member function 418 
TMQueueAs Vector member function 426 
TMQuueAsDoubleList member function 430 
TMStackAs Vector member function 438 

IsFull 

TMArray As Vector member function 357 
TMBag As Vector member function 375 
TMDequeAsDoubletist member function 39 1 
TMDequeAsVector member function 384 
TMIArrayAsVector member function 362 
TMIBagAs Vector member function 378 
TMIDequeAsDoubleList member function 393 
TMIDequeAsVector member function 388 
TMIQueueAsDoubleList member function 432 
TMIQueueAsVector member function 428 
TMIStackAs Vector member function 440 
TMQueueAsDoubleList member function 430 
TMQueueAs Vector member function 426 
TMStackAs Vector member function 438 

isgraph (function) 152 

islower (function) 152 

IsOpen, TFile member function 490 

isprint (function) 153 

ispunct (function) 153 

isspace (function) 154 

istream (class) 323 

istream_withassign (class) 325 

istrstream (class) 325 

isupper (function) 154 

IsValid 

TDate member function 485 



TTime member function 516 
isxdigit (function) 154 
ItemAt 

TMArrayAsVector member function 358 

TMIArrayAsVector member function 363 
IterFunc typedef 355, 361, 374, 376, 383, 387, 390, 

393, 402, 407, 417, 421, 437, 439, 444, 453 
itoa (function) 155 



Japanese date formats 57 

Jday, TDate member function 485 

JulTy, TDate type definition 483 

K 

kbhit (function) 155 

Key 

TMDD Association member function 368 
TMDIAssociation member function 370 
TMID Association member function 371 
TMIIAssociation member function 373 

keyboard 

buffer, pushing characters back into 286 
I/O 122, 123 

checking for 155 
operations 41 
reading characters from 122, 123 

KeyData, TMID Association data member 371 

keystrokes, checking for 155 



labs (function) 156 

LastThat 

TMArrayAsVector member function 357 
TMDequeAsDoubleList member function 391 
TMDequeAsVector member function 384 
TMDoubleListlmp member function 403 
TMIArrayAsVector member function 363 
TMIBagAs Vector member function 378 
TMIDequeAsDoubleList member function 394 
TMIDequeAsVector member function 388 
TMIDoubleListlmp member function 408 
TMIListlmp member function 422 
TMIQueueAsDoubleList member function 432 
TMIQueueAsVector member function 428 
TMIStackAs Vector member function 440 
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TMIVectorlmp member function 454 

TMListlmp member function 4 18 

TMQueueAsDoubleList member function 430 

TMQueueAs Vector member function 426 

TMStackAs Vector member function 438 

TMVectorlmp member function 445 
lconv structure 158 
ldexp (function) 156 
ldexpl (function) 156 
Idiv (function) 157 
Leap, TDate member function 485 
left, ios data member 319 
Left, TMDequeAsVector data member 385 
length 

of files 51, 99 

of strings 260 
Length, TFile member function 490 
length member functions 

string 497 

TSubString 505 
LessThan 

TBinarySearchTreelmp member function 380 

TIBinarySearchTreelmp member function 382 
lfind (function) 157 
libraries 

dynamic link, summary 7 

entry headings 25 

files (list) 4 

multithread support 23 

selecting 4 

static, summary 5 
Lim, TMVectorlmp data member 446 
Limit 

TMIVectorlmp member function 454 

TMVectorlmp member function 446 
limits.h (header file) 8 
line-buffered files 236 
linear searches 757, 166 
lines 

blank, inserting 144 

clearing to end of 54 

deleting 54, 66 
literal values, inserting into code 84 
local standard time 64, 67, 1 19, 135, 160 
locale 

current 158 

dynamically loadable 233 



enabling 233 

environment variable LANG 233 

functions list 16 

monetary information 158 

numeric formats 158 

printf 197 

scanf 222 

selecting 232 

_ JJSELOCALES 233 

locale.h (header file) 8 
localeconv (function) 158 
local time (function) 160 
Lock 507, 510 

constructor 507, 510 

destructor 508, 510 
lock (function) 161 
locking (function) 161 
locking.h (header file) 8 
LockRange, TFile member function 491 
locks, file-sharing 161, 288 
loglO (complex friend function) 468 
log (complex friend function) 468 
log (function) 162 
loglO (function) 163 
loglOl (function) 163 
logarithm 

base 10 163, 468 

complex numbers 468 

natural 162, 468 
logl (function) 162 
longjmp (function) 164 

header file 9 
low intensity 165 
LowerBound 

TMArray As Vector member function 357 

TMIArray As Vector member function 363 
lowercase 

characters 282 
checking for 152 

conversions 270, 283 

strings 260 
lowvideo, conbuf member function 312 
lowvideo (function) 165 
_lrotl (function) 165 
_lrotr (function) 165 
lsearch (function) 166 
lseek (function) 166 
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ltoa (function) 167 

M 

machine language instructions 

inserted into object code 84 
macros 

argument lists, header file 9 

assert 7, 31 

case conversion 282, 283 

character classification 151, 153, 154 
case 150, 152, 154 
header file 8 
integers 150, 152, 154 
printable characters 152, 153 

characters 8, 202 

ASCII conversion 282 

comparing two values 171, 177 

debugging, assert (header file) 7 

defining (header file) 9 

directory manipulation (header file) 8 

far pointer 178 

file deletion 210 

input ports 142, 143 

output ports 185, 186 

peek 188 

peekb 188 

poke 191 

pokeb 192 

streaming 349 

toascii 282 

variable argument list 289 
main (function) 19-22 

arguments passed to 19, 299, 300 
example 20 
wildcards 21 

compiled with Pascal calling conventions 22 

declared as C type 22 

global variables and 299, 300 

value returned by 22 
_makepath (function) 168 
malloc (function) 169 
malloc.h (header file) 8 
mantissa 113, 180 
math, functions, list 15 
math error handler, user-modifiable 169 
math.h (header file) 8 



math package, floating-point 108 
_matherr (function) 169 
_matherrl (function) 169 
Max 

TDate member function 485 
TTime member function 51 6 
max (function) 171 

max_waste, string member function 497 
MaxDate, TTime member function 517 
mblen (function) 7 72 
mbstowcs (function) 1 72 
mbtowc (function) 1 73 
mem.h (header file) 8 
memccpy (function) 1 74 
memchr (function) 174 
memcmp (function) 175 
memcpy (function) 1 75 
memicmp (function) 1 76 
memmove (function) 1 76 
memory 

access (DMA) 39, 41 
addresses 
returning byte from 188 
returning word from 188 
storing byte at 192 
storing integer at 191 
allocation 

dynamic 46, 1 1 1, 169, 209, 250 
errors 477 
freeing 92 
functions (list) 16 
memory models and 46, 92, 93 
_new_handler and 305 
reallocating, 93 
set_new_handler and 305 
checking 16 
copying 174, 175, 176, 181 

in small and medium memory models 180 
direct access (DMA) 39,41 
freeing 

in far heap 92 
in heap 111 

in small and medium memory models 92 
functions (list) 14 
header file 7, 8 
initialization 177 
initializing 235 
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screen segment, copying to 131 

size 40, 41,250 
determining 42 
memory blocks 

adjusting size in heap 93, 209 

free 137 
filling 139, 140 

initializing 177, 235 

searching 174 
memory .h (header file) 8 
memory management functions 8 
memory models, 

disk transfer address and 127 

DLL 7 

DOS system calls and 36 

functions 16 . 

libraries 4 

math files for 4 

memory allocation and 46, 92, 93 

moving data and 180 
memset (function) 1 77 
microprocessors 240 
midnight, number of seconds since 43 
Min 

TDate member function 485 

TTime member function 516 
min (function) 1 77 
Minute, TTime member function 516 
MinuteGMT, TTime member function 516 
mixing with BCD numbers 466 
mixing with complex numbers 466 
MK_FP (function) 775 
mkdir (function) 178 
mktemp (function) 779 
mktime (function) 179 
mnemonics, error codes 8, 302, 303 
modes, floating point, rounding 55 
modf (function) 750 
modfl (function) 180 
modulo 104 

Month, TDate member function 486 
MonthName, TDate member function 486 
MonthTy, TDate type definition 483 
MostDerived, TStreamableBase member function 

347 
movedata (function) 180 
movetext (function) 787 



movmem (function) 181 
_msize (function) 752 
multibyte characters 772 

converting to wchar_t code 7 73 
multibyte string, converting to a wchar_t array 7 72 
multithread 

initialization 37 

ResumeThread (function) 38 

Windows NT 37 
multithread libraries 23 

N 

name, Type_info member function 48 1 
NameOfDay, TDate member function 486 
NameOfMonth, TDate member function 486 
natural logarithm 762 
new 

TMDoubleListElement operator 407 

TMListElement operator 477 
new files 59, 60, 61, 69, 214 
new.h (header file) 6 
new_handler (function type) 478 
_new_handler (global variable) 305 
newline character 203 
Next 

TMDequeAs Vector member function 385 

TMDoubleListElement data member 407 

TMListElement data member 416 
NMI 67 

nocreate, ios data member 379 
nodes, checking on heap 736 
non-maskable interrupt 67 
nonlocal goto 64, 164, 231 
noreplace, ios data member 379 
norm (complex friend function) 468 
normal intensity 762 
norm video, conbuf member function 372 
norm video (function) 762 
not operator (!), overloading 345 
number of drives available 726 
numbers 

ASCII, checking for 752 

BCD (binary coded decimal) 463, 465 

complex 468 

functions (list) 75 

pseudorandom 206 

random 206, 207 
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generating 249 
rounding 46, 103 
turning strings into 33 
numeric coprocessors 

checking for presence of 40, 4 1 
control word 55 
exception handler 52, 251 
global variables 299 
problems with 109 
status word 51,251 



object code 

machine language instructions and 84 
OBSOLETE.LIB 17 
oct, ios data member 319 
oem_to_ansi, string member function 497 
offset, of far pointer 108, 1 78 
offsetof (function) 182 
ofpstream class 340 
ofstream (class) 326 
open (function) 183 

header file 8 
Open, TFile member function 491 
open member functions 

filebuf 315 

fpbase 336 

f stream 316 

fstreambase 317 

ifpstream 337 

if stream 318 

ofpstream 341 

ofstream 327 
open_mode, ios data member 319 
opendir (function) 185 
openprot, filebuf data member 314 
operating system 

command processor 272 

commands 272 

date and time, setting 251 

environment 

returning data from 127 
variables 88, 245 
accessing 301 

file attributes, shared 79,217 

path, searching for file in 226, 227 

search algorithm 87 



system calls 80, 21 7 

verify flag 237 

version number 306, 308 
operator « 

opstream friends 343 

writing prefix /suffix (streamable) 343 
operator ! (), pstream 345 
operator », ipstream friends 340 
operator void *(), pstream member function 345 
opfx, ostream member function 327 
opstream class 341 

friends 343 
osfx, ostream member function 327 
_osmajor (global variable) 306 
_osminor (global variable) 306 
ostream (class) 327 
ostream_withassign (class) 328 
ostrstream (class) 328 
_osversion (global variable) 306 
out, ios data member 319 
out_waiting, streambuf member function 330 
outp (function) 185 
outport (function) 186 
outportb (function) 186 
output 

characters, writing 201 

displaying 109, 195,291 

flag 301 

flushing 97 

formatting 58, 319 

to streams, formatting 109, 195, 291 
outpw (function) 186 
overflow member functions 

conbuf 372 

filebuf 315 

strstreambuf 333 
overloaded operators 345 
overwriting files 60 
OwnsElements, TShouldDelete member function 

461 



P_id_type 337, 341 

-p option (Pascal calling conventions), main function 

and 22 
parameter values for locking function 8 
parent process 87, 245 
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parsfnm (function) 187 

parsing file names 187 

Pascal calling conventions, compiling main with 
22 

passwords 130 

PATH environment variable 88, 245 

paths 

directory 226, 227 
finding 124 
names 

converting 120 
creating 105, 168 
splitting 106, 247 
operating system 226, 227 

pause (suspended execution) 242 

pbase, streambuf member function 331 

pbump, streambuf member function 331 

_pclose (function) 187 

pcount, ostrstream member function 329 

peek (function) 188 

peek, istream member function 324 

peekb (function) 188 

PeekHead 

TMDoubleListlmp member function 403 
TMIDoubleListlmp member function 408 
TMInternallListlmp member function 422 
TMListlmp member function 4 18 

PeekLeft 

TMDequeAsDoubleList member function 391 
TMDequeAs Vector member function 384 
TMIDequeAsDoubleList member function 394 
TMIDequeAs Vector member function 388 

PeekRight 

TMDequeAsDoubleList member function 391 
TMDequeAs Vector member function 384 
TMIDequeAsDoubleList member function 394 
TMIDequeAs Vector member function 388 

PeekTail 

TMDoubleListlmp member function 403 
TMIDoubleListlmp member function 409 

perror (function) 189, 302 
messages generated by 189 

persistent streams, macros 349 

PID (process ID) 130, See also processes 

_pipe (function) 190 

pointers 

to error messages 256, 257 



far 92, 93, 94 
address segment 108, 178 
creating 178 
offset of 108, 178 
file 
initialization 211 
moving 166 
obtaining 98 

resetting 80, 1 14, 208, 218 
returning 118 

current position of 274 
setting 1 15, 184, 243 
format specifiers 197, 222 
frame base 164,231 
stack 164,231 
stream buffers 345 

pstream 345 
to void, overloading 345 
PointerTypes, pstream data member 344 
poke (function) 191 
pokeb (function) 192 - 
polar (complex friend function) 468 
poly (function) 192 
polyl (function) 192 
polynomial equation 192 
Pop 

TMIStackAs Vector member function 440 
TMStackAs Vector member function 438 
_popen (function) 192 
ports 

checking for presence of 39, 40 
communications 39, 40, 151 
I/O 143, 144, 186 

macros 142, 143, 185 
writing to 755, 186 
position 
current 339 

stream 338 
streamable objects 339, 342 
Position, TFile member function 491 
POSIX directory operations 8 
powlO (function) 194 
pow (complex friend function) 468 
pow (complex numbers) 468 
pow (function) 193 
powlOl (function) 194 
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powers 

calculating ten to 194 

calculating values to 193 
powl (function) 193 
pptr, streambuf member function 331 
precision 

floating point 55 

format specifiers 196, 199, 200 
precision, ios member function 321 
PRECONDITION macro 472 
PRECONDITIONX macro 473 
prefixes, streamable object's name and 339, 343 
prepend, string member function 497 
Prev 

TMDequeAs Vector member function 385 

TMDoubleListElement data member 401 
Previous, TDate member function 486 
printable characters, checking for 152, 153 
PrintDate, TTime member function 516 
printers, checking for 39, 40, 151 
printf (function) 195 

conversion specifications 195 

format specifiers 195 . 

input-size modifiers 195 

locale support 197 
printing, error messages 189, 302 
process control, functions (list) 1 7 
process.h (header file) 8 
process ID 130 
processes 

child 87, 244 

exec... (functions), suffixes 88 

parent 87, 245 

stopping 27 
program segment prefix (PSP) 130 

current program 307 
programs 

loading and running 87 

process ID 130 

signal types 206 

stopping 27, 33, 64 
exit status 47, 89, 90 
request for 206 
suspended execution 242 

termination 478, 479 

TSR 49 
pseudorandom numbers 206 



PSP See program segment prefix 

_psp (global variable) 307 

pstream class 344 

punctuation characters, checking for 153 

Push 

TMIStackAs Vector member function 441 
TMStackAsVector member function 438 

Put 

TMIQueue AsDoubleList member function 432 
TMIQueueAsVector member function 428 
TMQueueAsDoubleList member function 430 
TMQueueAs Vector member function 426 

put, ostream member function 327 

put_at 

string member function 498 
TSubString member function 505 

putback, istream member function 324 

putc (function) 201 

putch (function) 201 

putchar (function) 202 

putenv (function) 202 

PutLeft 

TMDeque AsDoubleList member function 391 
TMDequeAs Vector member function 385 
TMIDequeAsDoubleList member function 394 
TMIDequeAs Vector member function 389 

PutRight 

TMDeque AsDoubleList member function 391 
TMDequeAs Vector member function 385 
TMIDequeAsDoubleList member function 394 
TMIDequeAs Vector member function 389 

puts (function) 203 

puttext (function) 203 

putw (function) 204 



Q 



qsort (function) 204 
quicksort algorithm 204 
quotient 67, 157 



raise (function) 205 

header file 9 
raise member function, xmsg 482 
raise member functions 

xalloc 481 
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RAM, size 40, 41, 42, 43 

rand (function) 206 

random (function) 207 

random number generator 206, 207 

initialization 207, 249 
random numbers 206, 207 
randomize (function) 207 
range facility shortcut 223 
rdbuf member functions 

constream 373 

fpbase 336 

f stream 316 

fstreambase 377 

ifpstream 337 

if stream 378 

ios327 

ofpstream 341 

ofstream 327 

pstream 345 

strstreambase 332 
rdstate 

ios member function 327 

pstream member function 345 
Read 

TFile member function 491 

TStreamer member function 348 
read (function) 207 
read, istream member function 324 
_dos_read (function) 79 
read error 97 

*ead_file, string member function 498 
read_line, string member function 498 
read_string, string member function 498 
read_to_delim, string member function 498 
read_token, string member function 498 
read/write flags 184, 243 
readByte, ipstream member function 338 
readBytes, ipstream member function 338 
readData, ipstream member function 339 
readdir (function) 208 
readPrefix, ipstream member function 339 
readString, ipstream member function 338 
readSuffix, ipstream member function 339 
read Version, ipstream member function 339 
readWordl6, ipstream member function 338 
readWord32, ipstream member function 338 
readWord, ipstream member function 338 



real friend functions 

bed 465 

complex 468 
realloc (function) 209 
Reallocate 

TMArrayAs Vector member function 358 

TMIArrayAsVector member function 363 
records, sequential 757 
ref .h (header file) 8 
RefDate, TTime data member 577 
RegClassName 347 
regexp.h (header file) 8 
register variables, as task states 764 
registerObject 

ipstream member function 338 

opstream member function 342 
registers, segment, reading 228 
registerVB, opstream member function 342 
registration types 347 
REGPACK structure 148 
remainder 67, 104,157 
remove (function) 270 
remove, string member function 498 
Remove, TFile member function 491 
RemoveEntry 

TMArrayAs Vector member function 358 

TMIArrayAsVector member function 363 
rename (function) 270 
Rename, TFile member function 491 
replace, string member function 499 
request for program termination 206 
requested member function, xalloc 482 
reserve, string member function 499 
Resize 

TMIVectorlmp member function 454 

TMVectorlmp member function 446 
resize, string member function 499 
resize_increment, string member function 499 
Restart 

TBinarySearchTreelteratorlmp member function 

380 

TIBinarySearchTreelteratorlmp member 

function 382 

TMArrayVectorlterator member function 359 

TMDequeAsVectorlterator member function 

386 
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TMDictionaryAsHashTablelterator member 

function 397 

TMDoubleListlteratorlmp member function 404 

TMHashTablelteratorlmp member function 413 

TMIArrayAsVectorlterator member function 

364 . 

TMIDictionaryAsHashTablelterator member 

function 399 

TMIDoubleListlteratorlmp member function 

409 

TMIHashTablelteratorlmp member function 

415 

TMIListlteratorlmp member function 423 

TMIVectorlteratorlmp member function 455 

TMLis titer atorlmp member function 419 

TMVectorlteratorlmp member function 447 
restoring screen 203 
Resume, TThread member function 512 
rewind (function) 21 1 
rewinddir (function) 211 
rfind, string member function 498 
right, ios data member 319 
Right, TMDequeAs Vector data member 385 
rmdir (function) 212 
rmtmp (function) 212 
rotation, bit 

long integer 165 

unsigned char 62 

unsigned integer 21 3 
_rotl (function) 213 
_rotr (function) 213 
rounding 46, 103 

banker's 464 

modes, floating point 55 
_rtl_chmod (function) 213 
_rtl_close (function) 214 
_rtl_creat (function) 214 
_rtl_write (function) 218 
_rtl_heap walk (function) 215 
_rtl_open (function) 216 

rtti type (Type_info class) 480 

run-time library 

functions by category 9 

source code, licensing 3 

s 

S IREAD 285 



SJWRITE 285 

sbumpc, streambuf member function 330 

scanf (function) 219 

format specifiers 219 

locale support 222 

termination 225 
conditions 226 
scientific, ios data member 31 9 
scratch files 

naming 274, 281 

opening 280 
screens 

clearing 54 

copying text from 181 

displaying strings 59 

echoing to 1 22, 123 

formatting output to 58 

modes, restoring 203 

saving 132 

segment, copying to memory 131 

writing characters to 201 
scrolling 309 
search.h (header file) 8 
search key 166 
_searchenv (function) 226 
searches 

appending and 1 66 

binary 44 

block, for characters 1 74 

header file 9 

linear 157, 166 

operating system 
algorithms 87 
path, for file 226, 227 

string 
for character 252 
for tokens 268 
searchpath (function) 227 
_searchstr (function) 227 
Second, TTime member function 516 
Seconds, TTime member function 516 
security, passwords 130 
seed number 249 
Seek, TFile member function 491 
seek_dir, ios data member 31 8 
seekg 

ipstream member function 339 
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istream member function 324 
seekoff member functions 

filebuf 315 

streambuf 330 

strstreambuf 333 
seekp 

opstream member function 342 

ostream member function 327, 328 
seekpos, streambuf member function 330 
SeekToBegin, TFile member function 491 
SeekToEnd, TFile member function 491 
segment prefix, program 130, 307 
segments 

far pointer 108, 178 

registers, reading 228 

scanning for characters in strings 266 

screen, copying to memory 131 
segread (function) 228 
sequential records 757 

set_case_sensitive, string member function 499 
set_new_handler (function) 305, 477 
set_paranoid_check, string member function 499 
set_terminate (function) 478 
set_unexpected (function) 479 
setb, streambuf member function 331 
setbuf (function) 228 
setbuf member functions 

filebuf 375 

fpbase 336 

fstreambase 377 

streambuf 330 

strstreambuf 333 
setcbrk (function) 229 
setcursortype, conbuf member function 372 
setcursortype (function) 230 
SetData 

TMArrayAs Vector member function 358 

TMIArray As Vector member function 364 
setdate (function) 73 
setdisk (function) 126 
setdta (function) 230 
setf, ios member function 327 

constants used with 373 
setftime (function) 129 
setg, streambuf member function 332 
setjmp (function) 237 

header file 9 



setjmp. h (header file) 9 

setlocale (function) 232 

setmem (function) 235 

setmode (function) 235 

setp, streambuf member function 332 

SetPrintOption, TDate member function 486 

SetPriority, TThread member function 572 

setstate 

ios member function 322 

pstream member function 346 
SetStatus, TFile member function 491 
settime (function) 733 
setting file read /write permission 285 
setvbuf (function) 236 
setvect (function) 734 
setverify (function) 237 
sgetc, streambuf member function 330 
sgetn, streambuf member function 330 
share .h (header file) 9 

ShouldTerminate, TThread member function 573 
showbase, ios data member 319 
showpoint, ios data member 319 
showpos, ios data member 375 
signal (function) 237 

header file 9 

multithread programs 23 
signal.h (header file) 9 
signals 

handlers 205, 206, 237 
interrupt handlers and 239 
returning from 240 
user-specified 237 

program 206 
sin (complex friend function) 469 
sin (function) 247 
sine 247 

complex numbers 469 

hyperbolic 247 

inverse 30 
sinh (complex friend function) 469 
sinh (complex numbers) 469 
sinh (function) 24 1 
sinhl (function) 247 
sinl (function) 247 
size 

file 57, 99 

memory 40, 41,42 
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skip_whitespace, string member function 499 

skipws, ios data member 319 

sleep (function) 242 

snextc, streambuf member function 330 

software signals 205, 206 

sopen (function) 242 

sorts, quick 204 

sounds, functions list 16 

source code, run- time library, licensing 3 

space on disk, finding 74, 126 

spawn... (functions), suffixes 245 

spawnl (function) 244 

spawnle (function) 244 

spawnlp (function) 244 

spawnlpe (function) 244 

spawnv (function) 244 

spawnve (function) 244 

spawnvp (function) 244 

spawnvpe (function) 244 

_splitpath (function) 247 

sprintf (function) 248 

format specifiers 195, 248 
sputbackc, streambuf member function 330 
sputc, streambuf member function 330 
spurn, streambuf member function 330 
sqrt (complex friend function) 469 
sqrt (function) 249 
sqrtl (function) 249 
square root 249 

complex numbers 469 
SqueezeEntry 

TMIArray As Vector member function 364 
srand (function) 249 
sscanf (function) 250 

format specifiers 219 
stack 46, 169 

pointer, as task states 164, 231 

size 250 
stackavail (function) 250 
standard time 64, 67, 119,135 
start, TSubString member function 505 
Start, TThread member function 512 
stat (function) 116 
stat structure 117 
state 

ios data member 320 

pstream data member 345 



read current pstream 345 

set current pstream 346 
_status87 (function) 251 
Status, TThread data member 511 
status word 

floating-point 51,251 

numeric coprocessors 51,251 
stdargs.h (header file) 9 
stdaux 94 

stddef .h (header file) 9 
stderr 94, 1 12 

header file 9 
stdin 94, 1 12 

buffers and 229 

header file 9 

reading 
characters from 98, 123 
input from 219, 292 
strings from 131 
stdio, ios data member 319 
stdio.h (header file) 9 
stdiostr.h (header file) 9 
stdlib.h (header file) 9 
stdout 94, 1 12 

buffers and 229 

header file 9 

writing 
characters to 110,202 
formatted output to 195, 291 
strings to 203 
stdprn 94 

header file 9 
s time (function) 251 
storage, invalid access 206 
stossc, streambuf member function 330 
stpcpy (function) 251 
str member functions 

ostrstream 329 

strstream 334 

strstreambuf 333 
strcat (function) 252 
strchr (function) 252 
strcmp (function) 253 
strcmpi (function) 253 
strcoll (function) 254 
strcpy (function) 255 
strcspn (function) 255 
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_strdate (function) 255 
strdup (function) 256 
streamable classes 

base class 344 

BUILDER typedef and 347 

creating 346, 347 

reading 337 
strings 338 

registering 347 

TStreamableBase 346 

TStreamableClass 347 

writing 34 1 
streamable objects 

basic operations 336 

finding 337, 341 

flushing 341 

position within 339, 342 

reading 336, 339 
current position 338 

writing 336, 340 
StreamableName, TStreamer member function 348 
streambuf (class) 329 
streaming macros 349 

DECLARE_ABSTRACT_STREAMABLE 350 

DECLARE_ABSTRACT_STREAMER 351 

DECLARE_CASTABLE 351 

DECLARE_STREAMABLE 349 

DECLARE_STREAMABLE_CTOR 351 

DECLARE_STREAMABLE_FROM_BASE 350 

DECLARE_STREAMABLE_OPS 357 

DECLARE_STREAMER 350 

DECLARE_STREAMER_FROM_BASE 351 

IMPLEMENT_ABSTRACT_STREAMABLE 353 

IMPLEMENT_CASTABLE_ID 353 

IMPLEMENT_STREAMABLE 352 

IMPLEMENT_STREAMABLE_CLASS 352 

IMPLEMENT_STREAMABLE_CTOR 352 

IMPLEMENT_STREAMABLE_POINTER 353 

IMPLEMENT_STREAMER 353 
streams 

buffer, pointer to 345 

closing 94, 1 12 

end of 344 

error and end-of-file indicators 52, 96, 97 

flushing 97, 103,341 

formatting input from 1 13, 290, 293 
stdin 219, 292 



header file ,9 

hierarchy 335 

I/O 96, 108, 112, 116 

pushing character onto 286 
initializing 346 
linking file handles to 95 
macros 349 
opening 107, 112, 115 
pointers 

file 114, 115 

initialization 21 1 
reading 

characters from 98, 122 

data from 111 

errors 344 

input from 7 13, 290, 293 
stdin 219 

integers from 735 

strings from 99 
reading and writing, errors 344 
registering 347 
replacing 772 
state 344 
stdaux 94 
stderr 94, 1 12 
stdprn 94 

terminated input 226 
tied 327 

unbuffered 229, 236 
writing 703, 720 

characters to 770, 207, 202 

errors 344 

formatted output to 709, 705, 290 
stdout 207 

integers to 204 

strings to 7 70, 203 
writing to 342, 343 
_strerror (function) 256 
strerror (function) 257 
strftime (function) 257 
stricmp (function) 259 
string 492 

!= operator 502 
() operator 507 
+= operator 507 
<= operator 503 
== operator 502 



550 



Library Reference 



>= operator 503 

» operator 503 

[] operator 501 

+ operator 501 

< operator 503 

= operator 501 

> operator 503 

ansi_to_oem member function 493 

append member function 493 

assign member function 494 

assignment operator 501 

c_str member function 494 

compare member function 494 

concatentation operator 501 

copy member function 494 

cow member function 501 

find_first_not_of member function 495 

find_first_of member function 495 

find_last_not_of member function 496 

find_last_of member function 496 

find member function 495 

get_case_sensitive_flag member function 496 

get_initial_capacity member function 496 

get_max_waste member function 496 

get_paranoid_check member function 497 

get_resize_increment member function 497 

get_skipwhitespace_flag member function 497 

hash member function 497 

initial_capacity member function 497 

is_null member function 497 

length member function 497 

max_waste member function 497 

oem_to_ansi member function 497 

prepend member function 497 

read_file member function 498 

readjine member function 498 

read_string member function 498 

read_to_delim member function 498 

read_token member function 498 

replace member function 499 

reserve member function 499 

resize_increment member function 499 

resize member function 499 

rfind member function 498 

set_case_sensitive member function 499 

set_paranoid_check member function 499 

skip_whitespace member function 499 



strip member function 500 
substr member function 500 
substring member function 500 
to_lower member function 500 
to_upper member function 500 
string.h (header file) 9 
strings 

appending 252 

parts of 261 
array allocation 338 
changing 277 
comparing 1 75, 253, 254 

ignoring case 1 76, 253, 259 

parts of 261 

ignoring case 262, 263 
concatenating 252, 261 
copying 251, 255 

new location 256 

truncating or padding 262 
displaying 59, 197 
duplicating 256 
format specifiers 197, 221 
formatting 248, 257, 293 
functions 14 

with multiple prototypes 9 
header file 9 
initialization 263, 265 
length, calculating 260 
lowercase 260 
reading 221, 338 

formatting and 250 

from console 48 

from streams 99, 131 
reversing 265 
searching 

for character 252 
in set 264 

last occurrence of 264 
not in set 255 

for segment in set 266 

for substring 266 

for tokens 268 
space allocation 338 
transforming 271 
uppercase 270 
writing 

formatted output to 248, 293 
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to current environment 202 
to screen 59 
to stdout 203 
to streams 110,342 
strip, string member function 500 
StripType, string type definition 492 
strlen (function) 260 
strlwr (function) 260 
strncat (function) 261 
strncmp (function) 261 
strncmpi (function) 262 
strncpy (function) 262 
strnicmp (function) 263 
strnset (function) 263 
strpbrk (function) 264 
strrchr (function) 264 
strrev (function) 265 
strset (function) 265 
strspn (function) 266 
strstr (function) 266 
strstrea.h (header file) 9 
strstream (class) 334 
strstreambase (class) 332 
strstreambuf (class) 332 
_strtime (function) 266 
strtod (function) 267 
strtok (function) 268 
strtol (function) 269 
_strtold (function) 267 
strtoul (function) 270 
struct DOSERROR 71 
struct heapinfo 141 
structures 

REGPACK 148 

stat 117 
strupr (function) 270 
strxfrm (function) 271 
substr, string member function 500 
substring, string member function 500 
substrings, scanning for 266 
suffixes 

exec... 88 

spawn... 245 

streamable object's name and 339, 343 
support for variable-argument functions 9 
Suspend, TThread member function 512 
suspended execution, program 242 



swab (function) 272 
swapping bytes 272 
sync member functions 

filebuf 315 

strstreambuf 333 
sync_with_stdio, ios member function 321 
sys\stat.h (header file) 9 
sys\ types. h (header file) 9 
_sys_errlist (global variable) 302 
_sys_nerr (global variable) 302 
system 

buffers 94 

commands, issuing 272 

equipment interrupt 39, 40 

error messages 189, 302 
system (function) 272 



T constructor 

TBinarySearchTreelteratprlmp 380, 382 

TMDictionaryAsHashTablelterator 396, 399, 

400 

TMIHashTablelmp 414 
tables, searching 44, 166 
Tail 

TMDoubleList data member 403 

TMListlmp data member 419 
tan (complex friend function) 469 
tan (function) 273 
tangent 273, 469 

complex numbers 469 

hyperbolic 273 

inverse 31, 32 
tanh (complex friend function) 469 
tanh (function) 273 
tanhl (function) 273 
tanl (function) 273 
TArrayAs Vector 360 

constructor 360 
TArrayAsVectorlterator 360 

constructor 360 
task states 

defined 164, 231 

register variables 164 
TBagAs Vector 376 

constructor 376 
TBagAs Vectorlterator 376 
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constructor 376 
TBinarySearchTreelmp 379 
TBinarySearchTreelteratorlmp 380 
TCriticalSection 507 

constructor 507 

destructor 507 
TCVectorlmp 451 

constructor 451 
TCVectorlteratorlmp 451 
TDate 483 

constructor 484 
TDD Association 369 

constructor 369 
TDeque constructor 387 
TDequeAsDoubleList 392 
TDequeAsDoubleListlterator 392 

constructor 392 
TDequeAsVector 386 

constructor 386 
TDequeAsVectorlterator 387 
TDIAssociation 370 

constructor 370 
TDictionary 400 
TDictionary AsHashTable 397 

constructor 397 
TDictionary AsHashTablelterator 397 

constructor 398 
TDictionarylterator 400 

constructor 401 
TDoubleListlteratorlmp 405 

constructor 405 
tell (function) 274 
tellg 

ipstream member function 339 

istream member function 325 
tellp 

opstream member function 342 

ostream member function 328 
template (file names) 1 79 
tempnam (function) 274 
temporary files 

naming 274, 281 

opening 280 

removing 212 
terminals, checking for 15 1 
terminate (function) 479 
Terminate, TThread member function 513 



TerminateAndWait, TThread member function 

513 
terminating 

input from streams 226 
software signals 206 
termination function 33 
testing conditions 31 
text 

attributes 275, 277, 278 
background color, setting 275, 277 
colors 278 
copying 

from one screen rectangle to another 181 
to memory 131 
to screen 203 
intensity 
high 14 1 
low 165 
normal 182 
modes (screens) 203, 279, 297 
character color 275, 278 
coordinates 132 
copying to memory 131 
video information 132 
text files 

creat and 59 
creattemp and 61 
_dos_read and 80 
fdopen and 96 
fopenand 107 
freopenand 112 
_fsopenand 116 
_rtl_read and 217 
reading 208 
setting 235 
mode 96, 107, 1 12, 1 16, 305 
textattr (conbuf member functions) 312 
textattr (function) 275 

textbackground (conbuf member function) 312 
textbackground (function) 277 
textcolor (conbuf member function) 312 
textcolor (function) 278 
textmode (function) 279 
textmode member functions 
conbuf 312 
constream 313 
TFile 488 
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constructor 490 
TFileStatus 488 
THashTablelmp 413 

constructor 413 
THashTablelteratorlmp 414 

constructor 414 
thread ID 307 
Jhreadid (global variable) 23, 307 

throwExceptionName (global variable) 307 

throwFileName (global variable) 307 

throwLineNumber (global variable) 307 

TIArrayAs Vector 365 

constructor 365 
TIArrayAsVectorlterator 365 

constructor 365 
TIBagAs Vector 378 

constructor 378 
TIBagAs Vectorlterator 379 

constructor 379 
TIBinarySearchTreelmp 381 
TIBinarySearchTreelteratorlmp 382 
TICVectorImp 458 

constructor 458 
TIDAssociation 372 

constructor 372 
TIDequeAsDoubleList 395 
TIDequeAsDoubleListlterator 395 

constructor 395 
TIDequeAs Vector 389 

constructor 389 
TIDequeAs Vectorlterator 390 

constructor 390 
TIDictionaryAsHashTable 400 
TIDictionaryAsHashTablelterator 400 

constructor 400 
TIDoubleListImp470 
TIDoubleListlteratorlmp 410 

constructor 410 
tie, ios member function 321 
tied streams 321 
TIHashTableImp476 
TIHashTablelteratorlmp 416 

constructor 416 
TIIAssociation 373 

constructor 373 
TIListlteratorlmp 423 

constructor 423 



time 
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system 30, 63, 1 19, 135 
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local 160 
returning 77, 133 
setting 77, 133, 251 
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arrays 308 
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constructor 437 
TMStackAs Vectorlterator 438 

constructor 438 
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TMutex 508 

constructor 508 

destructor 508 

HANDLE operator 508 
TMutex::Lock 508 

constructor 509 
to_lower 

global string function 504 

string member function 500 

TSubString member function 505 
to_upper 

global string function 504 

string member function 500 

TSubString member function 505 
toascii (function) 282 
tokens, searching for in string 268 
_tolower (function) 282 
tolower (function) 282 
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toupper (function) 283 
TQueue 433 
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TQueueAs Vector 427 

constructor 427 
TQueueAs Vectorlterator 427 

constructor 427 
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__TRACE debugging symbol 471 
TRACE macro 472 
TRACEX macro 473 
translation mode 59, 61, 305 
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trigonometric functions 

arc cosine 28 
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arc tangent 31, 32 
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hyperbolic 56 
inverse 28 

hyperbolic tangent 273 

sine 241 
hyperbolic 241 
inverse 30 

tangent 273 
hyperbolic 273 
inverse 31, 32 
trunc, ios data member 319 
TSArrayA's Vector 366 

constructor 366 
TSArrayAs Vectorlterator 366, 367 

constructor 367 
TSDoubleListlmp 406 
TSDoubleListlteratorlmp 407 

constructor 407 
TSet 436 
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TSetAs Vector 434 
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constructor 435 
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TStackAsList 442 
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TStackAsVectorlterator 439 
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MostDerived member function 347 
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DELTA macro 348 
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constructor 348 

GetObject member function 348 

Read member function 348 

StreamableName member function 348 

Write member function 349 
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get_at member function 505 
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put_at member function 505 
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to_upper member function 505 
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GetStatus member function 512 

Resume member function 512 
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ShouldTerminate member function 513 
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Suspend member function 512 

Terminate member function 513 

TerminateAndWait member function 513 

WaitForExit member function 513 
TThreadError 513 

ErrorType data member 514 
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++ operator 577 

+= operator 518 

— operator 517 

-= operator 518 

« operator 518 
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AsString member function 515 

BeginDST member function 515 

Between member function 515 

CompareTo member function 515 
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EndDST member function 516 

Hash member function 516 

Hour member function 516 

HourGMT member function 516 

IsDST member function 516 
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Minute member function 516 
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PrintDate member function 516 

RefDate data member 517 

Second member function 516 

Seconds member function 516 
TVectorlmp 448 

constructor 448 
TVectorlteratorlmp 448 

constructor 448 
type checking, device 151 
Type_id, TStreamable base typedef 346 
Type_info class 480 
typeid operator (Type_info class) 480 
typeinfo.h (header file) 9 
_tzname (global variable) 308 

setting value of 283 
tzset (function) 283 

u 

U.S. date formats 57 

ultoa (function) 285 

umask (function) 285 

unbuffered, streambuf member function 332 

unbuffered streams 229, 236 

undefined external 16 

underflow member functions 

filebuf 315 

strstreambuf 334 
unexpected (function) 481 
ungetc (function) 286 
ungetch (function) 286 
unitbuf, ios data member 319 
UNIX 

constants, header file 9 

date and time 
converting DOS to 81 
converting to DOS format 287 
unixtodos (function) 287 
unlink (function) 287 
unlock (function) 288 
UnlockRange, TFile member function 491 
unsetf, ios member function 321 
UpperBound 

TMArray As Vector member function 358 

TMIArray As Vector member function 363 
uppercase 

characters 154, 283 

checking for 154 



conversions 260, 282 

strings 270 
uppercase, ios data member 319 
USELOCALES 

international support 
API, enabling 14 
macro 233 
user-defined comparison function 205 
user-defined formatting flags 322 
user hook 170 

user-modifiable math error handlers 169 
user-specified signal handlers 237 
utime (function) 288 
utime.h (header file) 9 

V 

va_arg (function) 289 

va_arg (variable argument macro) 289 

va_end (function) 289 

va_list (variable argument macro) 289 

va_start (function) 289 

va_start (variable argument macro) 289 

valid_element, string member function 501 

valid_index, string member function 507 

Value 

TMDD Association member function 368 

TMDIAssociation member function 370 

TMIDAssociation member function 371 

TMIIAssociation member function 373 
ValueData, TMIDAssociation data member 371 
values 

calculating powers to 193, 194 

comparing 171,177 

literal 84 
values.h (header file) 9 
varargs.h (header file) 9 
variables . ' 

argument list 289 

conversion specifications and 195 

environment 88, 245, 301 
COMSPEC272 

register 164 
verify flag (DOS) 134 
verify the heap 140 
version numbers 

DOS 306 

operating system 308 
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_version (global variable) 308 
vfprintf (function) 290 

format specifiers 195 

variable argument list 289 
vfscanf (function) 290 

format specifiers 219 

variable argument list 289 
video 

checking for 151 

information, text mode 132 

mode, checking 40, 41 

output flag 301 
void *(), pstream operator 345 
vprintf (function) 291 

format specifiers 195 

variable argument list 289 
vscanf (function) 292 

format specifiers 219 

variable argument list 289 
vsprintf (function) 293 

format specifiers 195 

variable argument list 289 
vsscanf (function) 293 

format specifiers 219 

variable argument list 289 

w 

wait (function) 294 

WaitForExit TThread member function 513 

_ _WARN debugging symbol 471 

WARN macro 472 

WARNX macro 473 

wcstombs (function) 295 

wctomb (function) 295 

WeekDay, TDate member function 486 

wherex, conbuf member function 312 

wherex (function) 296 

wherey, conbuf member function 312 

wherey (function) 296 

whitespace, checking for 754 

why member function, xmsg 482 

width, ios member function 322 

WILDARGS.OBJ 21 

wildcards, expansion 21 

by default 22 

from the IDE 22 
window (function) 297 
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conbuf 312 

constream 313 
windows 

functions (list) 10 

scrolling 309 

text 
cursor position 136, 296 
defining 297 
deleting lines in 54, 66 
inserting blank lines in 144 
words 

floating-point control 55 

reading from hardware ports 143, 144 

returning from memory 188 

writing to hardware ports 185, 186 

writing to streams 342 
Write 

TFile member function 491 

TStreamer member function 349 
write (function) 298 
write, ostream member function 328 
write error 97 

writeByte, opstream member function 342 
writeBytes, opstream member function 342 
writeData, opstream member function 343 
writeObjectPointer, opstream member function 

342 
writeObjectPtr, opstream member function 342 
writePrefix, opstream member function 343 
writeString, opstream member function 342 
writeSuffix, opstream member function 343 
writeWordl6, opstream member function 342 
writeWord32, opstream member function 342 
writeWord, opstream member function 342 



x_fill, ios data member 319 
x_flags, ios data member 319 
x_precision, ios data member 319 
x_tie, ios data member 320 
x_width, ios data member 320 
xalloc (class) 481 
xalloc, ios member function 322 
xmsg (class) 482 
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Year, TDate member function 486 
YearTy, TDate type definition 483 
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Zero 

TMIVectorlmp member function 455 
TMVectorlmp member function 446 

ZeroBase 

TMArray As Vector member function 358 
TMIArrayAs Vector member function 364 
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